人工智能AI 应用语音音视频【免费下载链接】VideoCaptioner 卡卡字幕助手 | VideoCaptioner - 基于 LLM 的智能字幕助手 - 视频字幕生成、断句、校正、字幕翻译全流程处理- A powered tool for easy and efficient video subtitling.项目地址https://gitcode.com/gh_mirrors/vi/VideoCaptioner点击查看免费下载本篇指南聚焦 VideoCaptioner 桌面发布版的完整构建链路从本地用 PyInstaller 打包出免安装 zip 包到 GitHub Actions 在 Windows / macOS 上自动构建并随v*标签发布。读者将掌握三条核心构建命令的用法、构建脚本与冒烟测试脚本的源码级原理、运行时用户数据目录的设计逻辑以及桌面 zip 与 PyPI 包双通道发布的工作流配置。桌面发布方案总览VideoCaptioner 以「桌面可执行包」与「PyPI Python 包」两种形态对外发布。其中桌面版由 GitHub Actions 在 Windows 和 macOS 上构建产物为 zip 压缩包用户从 GitHub Release 下载后解压即可运行其中的VideoCaptioner可执行文件Windows 下为VideoCaptioner.exe。桌面包的核心价值在于零依赖用户不需要预先安装 Python 环境也不需要单独安装 FFmpeg——构建时会将静态编译的ffmpeg/ffprobe一并打进应用包内resource/bin目录开箱即用。这一方案的关键决策记录在 docs/guide/desktop-release.md对应的可执行代码位于 scripts/build_desktop.py、scripts/smoke_desktop.py、VideoCaptioner.spec自动化流水线则定义在 .github/workflows/build-desktop.yml。本地构建桌面包三条命令在任意支持 Python 3.12 的机器上可以完整复现与 CI 一致的构建流程。整个流程只需要三条命令uv sync --frozen uv run --with pyinstaller --with static-ffmpeg python scripts/build_desktop.py --clean uv run python scripts/smoke_desktop.py dist/VideoCaptioner各命令职责如下命令作用uv sync --frozen依据uv.lock锁定版本安装项目依赖--frozen保证完全按锁定文件还原不重新解析项目依赖清单见 pyproject.tomluv run --with pyinstaller --with static-ffmpeg python scripts/build_desktop.py --clean临时注入 PyInstaller 与 static-ffmpeg 两个构建期依赖执行桌面构建脚本--clean表示先清空build/、dist/、artifacts/三个目录再构建uv run python scripts/smoke_desktop.py dist/VideoCaptioner对打包产物运行「真实打包应用」冒烟测试验证可执行文件、内置 FFmpeg 与字幕合成链路均可用其中--with是 uv 的临时依赖注入机制将构建所需的工具链依赖隔离在构建命令内避免污染项目自身的锁定依赖树。构建产物目录约定为dist/VideoCaptioner可执行 bundle、artifacts/VideoCaptioner-版本-平台.zip发布用压缩包见 scripts/build_desktop.py 的路径常量定义。构建脚本源码解析五个阶段scripts/build_desktop.py 的main()按顺序执行五个阶段L167-L182版本解析_version()依次尝试importlib.metadata.version(videocaptioner)→hatchling version→git describe --tags --always三级回退最终版本号会去除v前缀L29-L54版本文件生成ensure_version_file()若videocaptioner/_version.py不存在则自动写入__version__保证源码树与打包产物版本一致L57-L62静态 FFmpeg 准备prepare_ffmpeg()通过static_ffmpeg.run按当前平台键下载静态ffmpeg/ffprobe到build/static-ffmpeg/platform缓存再拷贝进build/desktop-runtime/resource/bin并在非 Windows 平台补齐可执行权限位L72-L97PyInstaller 构建build_pyinstaller()设置VIDEOCAPTIONER_DESKTOP_RUNTIME_DIR环境变量指向 runtime 目录后以VideoCaptioner.spec为配方调用python -m PyInstaller输出到dist/L100-L113产物校验与归档verify_bundle()/archive()先校验 bundle 中 5 项必需资源存在再按系统-架构标签如windows-x64、macos-x64生成 zipmacOS 平台若存在.app包还会额外生成-app.zipL116-L164。打包必需资源清单verify_bundle()硬性要求以下文件全部存在否则构建失败L135-L155_internal/resource/assets/logo.png应用图标资源_internal/resource/fonts/NotoSansSC-Regular.ttf中文字体_internal/resource/subtitle_style/ass-default.json默认字幕样式_internal/resource/bin/ffmpeg或ffmpeg.exeWindows_internal/resource/bin/ffprobe或ffprobe.exeWindows该清单与 VideoCaptioner.spec 中datas声明的资源打包范围一一对应resource/assets、resource/fonts、resource/subtitle_style、resource/translations、videocaptioner/core/prompts以及 runtime 目录下的resource/bin。默认样式文件位于 resource/subtitle_style含ass-default.json、ass-anime.json、ass-vertical.json、rounded-default.json四套预设。PyInstaller 配方的关键配置VideoCaptioner.spec 是打包的「食谱」值得关注的三点hiddenimports显式声明 PyQt5 全家桶QtCore/QtGui/QtWidgets/QtMultimedia/QtSvg以及openai、requests、edge_tts、diskcache、yt_dlp、modelscope、psutil、json_repair、langdetect、pydub、tenacity、GPUtil、PIL、fontTools等动态导入的第三方库并对qfluentwidgets执行collect_submodules全量收集L32-L60excludes剔除tkinter、matplotlib、scipy、pytest、ruff等与运行时无关的包显著减小体积L62-L72入口分析入口为videocaptioner/__main__.py即 CLI 主入口macOS 平台额外生成VideoCaptioner.appbundle并写入CFBundleName、CFBundleDisplayName、NSHighResolutionCapable等 Info.plist 字段L121-L131。运行时数据目录升级不丢配置的关键设计桌面包构建时还解决了一个常见痛点应用升级时用户数据不丢失。构建脚本将 FFmpeg 打进只读的 bundle 内而运行时的设置、日志、缓存、模型、自定义字幕样式全部存放在系统用户数据目录。这一逻辑在 videocaptioner/config.py 中实现核心是_IS_FROZEN判定getattr(sys, frozen, False)即 PyInstaller 打包运行态模式判定条件资源路径用户数据路径打包运行frozensys.frozen为真sys._MEIPASS/resourcebundle 内platformdirs.user_data_path(VideoCaptioner)即系统用户数据目录开发运行dev源码树旁存在resource/且未打包仓库根resource/仓库根AppData/pip 安装其余情况包内或用户数据目录用户数据目录可写数据BIN_PATH、SUBTITLE_STYLE_PATH、FONTS_PATH、LOG_PATH、CACHE_PATH、MODEL_PATH、SETTINGS_PATH在打包模式下全部落在用户数据目录L57-L72因此升级时只需替换程序文件本身。同时首次启动时会通过_copy_missing_tree()将 bundle 内的默认字幕样式与字体只拷贝缺失项到用户目录L80-L99保证默认配置可用又不覆盖用户的自定义样式。一个值得注意的细节运行时 PATH 的注入顺序是Faster-Whisper-XXL→ 用户bin→ bundle 内binL101-L105即用户自下载的工具优先于内置 FFmpeg内置版本作为兜底——这与smoke_desktop.py中「优先 bundle 内工具」的查找逻辑互为印证。打包应用冒烟测试真实产物级验证与只做「能否启动」的浅层检查不同scripts/smoke_desktop.py会针对打包产物执行一组端到端真实功能验证这也是本地构建流程与 CI 的最后一环。其执行步骤L108-L170定位可执行文件支持直接传dist/VideoCaptioner目录脚本按平台自动匹配VideoCaptioner.exe、VideoCaptioner或VideoCaptioner.app/Contents/MacOS/VideoCaptionerL21-L33定位内置工具按_internal/resource/bin、resource/bin、.app/Frameworks、.app/Resources多个候选路径查找内置ffmpeg/ffprobe找不到才回退系统 PATHL36-L50生成测试素材写入一条含中英文的示例 SRTL53-L62并用内置 FFmpeg 以testsrc2画面 sine音频生成 3 秒测试视频L65-L90运行真实命令依次执行--version、style列出字幕样式预设、doctor --json依赖诊断、两次synthesize分别以--subtitle-mode soft生成软字幕、--subtitle-mode hard --quality low烧录硬字幕校验产物用内置ffprobe读取输出视频的 JSON 时长确认文件存在、非空且时长 ≥ 2.5 秒否则抛错L162-L168。整个过程在临时目录中进行并将VIDEOCAPTIONER_LLM_API_KEY、VIDEOCAPTIONER_TTS_API_KEY置空以确保不依赖外部 API。这套冒烟测试对应的 CLI 命令定义在 videocaptioner/cli/main.pystyle命令见 L406-L418synthesize命令见 L217-L255。CI 自动化构建与发布桌面包由 GitHub Actions 工作流 .github/workflows/build-desktop.yml 自动构建。触发条件pull_request涉及videocaptioner/**、resource/**、构建脚本、spec、依赖锁定文件或工作流本身的变更时触发push推送到master/main分支或推送v*标签workflow_dispatch支持手动触发。并发策略为按desktop-${{ github.ref }}分组并取消进行中的同组任务避免重复构建浪费资源L25-L27。构建矩阵文档描述的构建平台为 Windows 与 macOS当前仓库实际配置的矩阵L36-L41为任务名运行环境Windows x64windows-latestmacOS Intelmacos-15-intel每个 job 设 45 分钟超时fail-fast: false保证单平台失败不影响另一平台继续构建。流水线步骤actions/checkoutv6拉取完整历史fetch-depth: 0保证版本解析能取到 git tagastral-sh/setup-uv安装 uvactions/setup-python指定 Python 3.12uv sync --frozen安装依赖uv run --with pyinstaller --with static-ffmpeg python scripts/build_desktop.py --clean构建桌面包与本地命令完全一致uv run python scripts/smoke_desktop.py dist/VideoCaptioner运行冒烟测试actions/upload-artifactv7上传artifacts/*.zip为工作流产物保留 14 天若为v*标签则用gh release创建/复用 Release 并上传 zip--clobber覆盖同名资产L73-L82。双通道发布桌面 zip 与 PyPI 包打v*标签时桌面工作流将 zip 上传至 GitHub Release与此同时独立的 PyPI 发布工作流 .github/workflows/publish-pypi.yml 也会在同一标签上运行将 Python 包发布到 PyPI 并把 wheel/sdist 上传到同一个 Release。PyPI 工作流由四个串行 job 组成qualityruff 检查、pyright 类型检查 CLI、运行tests/test_cli/单元测试→builduv build产出分发物→publish使用 OpenID Connect 信任的pypa/gh-action-pypi-publish免密发布→release创建 GitHub Release 并上传构建产物。因此一个v*标签发布后用户有两种获取方式下载桌面 zip 免环境运行或pip install videocaptioner以 Python 包方式使用两种产物并存于同一 Release。构建实践要点与排查建议综合脚本、spec 与工作流本地或 CI 构建桌面包时有几点值得注意务必使用--clean构建脚本会在多平台产物之间复用build/desktop-runtime与dist/跨平台构建前清理可避免残留旧平台二进制静态 FFmpeg 仅服务桌面包prepare_ffmpeg()依赖static-ffmpeg包按平台下载若环境无法联网或缺少该依赖脚本会明确报错并提示使用uv run --with ... static-ffmpeg的完整命令L79-L83smoke test 是发布前置关卡CI 中构建与冒烟测试在同一 job 内先后执行任何一步失败都不会进入 artifact 上传与 Release 步骤保证了发布产物「可用而非仅可启动」macOS 产物形态PyInstaller 的COLLECT生成dist/VideoCaptioner目录spec 在 darwin 平台额外生成dist/VideoCaptioner.app归档脚本对两者分别生成 zipL158-L164版本一致性构建版本来自包元数据、hatchling 或 git 标签三级回退发布时建议以v*标签为准确保 zip 文件名VideoCaptioner-version-platform.zip与 Release 标题一致。通过本地三条命令即可复现官方桌面包的构建与验证全流程若需自动化多平台发布直接复用 .github/workflows/build-desktop.yml 的矩阵与步骤配置即可。赞分享人工智能AI 应用语音音视频【免费下载链接】VideoCaptioner 卡卡字幕助手 | VideoCaptioner - 基于 LLM 的智能字幕助手 - 视频字幕生成、断句、校正、字幕翻译全流程处理- A powered tool for easy and efficient video subtitling.项目地址https://gitcode.com/gh_mirrors/vi/VideoCaptioner点击查看免费下载相关推荐CI/CD集成自动化构建与发布流程CI/CD集成自动化构建与发布流程 痛点多包管理项目的发布困境 你是否曾经面临这样的困境一个包含多个子包monorepo的前端项目每次发布新版本都需前端UI组件Flutter 生态包发布指南自动 CI 发布、批量发布与坏版本恢复全流程Flutter 生态包发布指南自动 CI 发布、批量发布与坏版本恢复全流程 本文基于 Flutter 仓库中面向生态团队的发布文档 release/READM跨平台移动开发前端UI组件桌面应用VoiceStudio 桌面端构建实战Tauri v2 PyInstaller 侧车进程打包与 macOS 发布全流程VoiceStudio 桌面端构建实战Tauri v2 PyInstaller 侧车进程打包与 macOS 发布全流程 本文以仓库内 docs/deskt人工智能语音音频本地部署MCP 服务桌面应用上一篇多平台部署AnonAddy DockerLinux/amd64与arm64环境适配指南下一篇KOReader终极指南免费开源电子书阅读器快速上手完整教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考