音视频AI 应用后端前端【免费下载链接】autoclipAutoClip : AI-powered video clipping and highlight generation · 一款智能高光提取与剪辑的二创工具项目地址https://gitcode.com/GitHub_Trending/autoc/autoclip点击查看免费下载本文以 docs/OPTIONAL_SRT_UPLOAD_GUIDE.md 为核心骨架结合 AutoClip 仓库的 projects.py、speech_recognizer.py、import_processing.py 与 FileUpload.tsx 等源码系统讲解字幕文件可选上传模式的接口设计、语音识别服务配置、前端交互改造与故障排查帮助开发者在自己的部署中启用并调优这一功能。AutoClip 是一款 AI 驱动的视频高光提取与剪辑工具其核心流水线依赖视频对应的字幕SRT文件来定位精彩片段。传统上传流程要求用户必须同时导入字幕文件这给没有现成字幕的普通用户设置了较高的使用门槛。本指南介绍的可选 SRT 上传功能允许用户只上传视频由系统自动调用语音识别服务生成字幕从而将创建剪辑项目的前置条件从视频 字幕降为仅视频同时保留用户提供字幕优先的智能降级策略。功能总览两种上传模式与智能决策启用该功能后POST /api/v1/projects/upload接口同时支持两种输入组合视频 字幕文件用户同时上传视频和 SRT 字幕文件系统直接使用用户提供的字幕保证内容与说话人意愿完全一致仅视频文件用户只上传视频系统自动调用语音识别服务默认本地 Whisper生成字幕确保流水线可以继续执行。对应的智能上传模式决策逻辑遵循三个原则见 projects.py 与 import_processing.py 的实现用户优先只要srt_file非空就保存用户字幕并跳过识别流程AI 辅助srt_file为空时在异步导入任务中调用generate_subtitle_for_video生成字幕错误处理语音识别彻底失败时向用户返回清晰的错误信息并提示可手动补传字幕或检查语音识别服务配置。此外功能还支持15 种语言的语音识别中文 zh、繁体中文 zh-TW、英文 en/en-US/en-GB、日文 ja、韩文 ko、法文 fr、德文 de、西班牙文 es、俄文 ru、阿拉伯文 ar、葡萄牙文 pt、意大利文 it以及自动检测 auto完整枚举见 speech_recognizer.py并根据视频分类智能选择识别语言商业/知识类视频优先使用中文识别娱乐类及其他类型默认自动检测语言。API 接口变化详解上传接口POST /api/v1/projects/upload核心变化是srt_file从必填变为可选。源码中 projects.py 的实际签名如下router.post(/upload, response_modelProjectResponse) async def upload_files( video_file: UploadFile File(...), srt_file: Optional[UploadFile] File(None), # 变为可选 project_name: str Form(...), video_category: Optional[str] Form(None), project_service: ProjectService Depends(get_project_service) ):请求示例场景一同时上传视频和字幕files { video_file: (video.mp4, video_content, video/mp4), srt_file: (subtitle.srt, srt_content, application/x-subrip) } data { project_name: 我的项目, video_category: knowledge }场景二仅上传视频字幕由 AI 生成files { video_file: (video.mp4, video_content, video/mp4) } data { project_name: 我的项目, video_category: knowledge }响应示例成功响应的结构保持不变但项目描述与settings会反映字幕处理方式。源码中 projects.py 在创建项目数据时会记录subtitle_info用户提供字幕时写入字幕文件名否则写入Whisper自动生成{ id: project-id, name: 我的项目, description: Video: video.mp4, Subtitle: Whisper自动生成, settings: { video_category: knowledge, video_file: video.mp4, srt_file: Whisper自动生成 } }参数与文件格式校验接口对上传文件做了严格的格式校验projects.py# 视频文件验证必需 if not video_file.filename.lower().endswith((.mp4, .avi, .mov, .mkv, .webm)): raise HTTPException(status_code400, detailInvalid video file format) # 字幕文件验证可选提供时才校验 if srt_file and not srt_file.filename.lower().endswith(.srt): raise HTTPException(status_code400, detailInvalid subtitle file format)视频支持 MP4、AVI、MOV、MKV、WebM 五种格式字幕仅接受.srt后缀。任一校验失败均返回 400 错误。错误处理语音识别失败当用户只上传视频、而所有可用的语音识别服务都不满足条件时系统返回 400{ detail: 语音识别失败: 没有可用的语音识别服务请安装whisper或配置API密钥。请手动上传字幕文件或检查语音识别服务配置。 }该错误信息与 speech_recognizer.py 中generate_subtitle_for_video的auto模式行为一致当按优先级遍历所有服务均不可用时抛出SpeechRecognitionError(没有可用的语音识别服务请安装whisper或配置API密钥)。后端实现原理从上传到字幕生成的关键调用链1. 文件落盘与异步任务提交上传接口在保存文件后通过 Celery 提交异步导入任务projects.pysrt_path None if srt_file: # 用户提供了字幕文件保存到项目 raw 目录 srt_path raw_dir / input.srt with open(srt_path, wb) as f: content await srt_file.read() f.write(content) # 提交异步任务srt_file_path 为 None 时触发语音识别 celery_task process_import_task.delay( project_idproject_id, video_pathstr(video_path), srt_file_pathstr(srt_path) if srt_path else None )其中raw_dir get_project_raw_directory(project_id)来自 path_utils.py视频统一落盘为input.mp4用户字幕统一落盘为input.srt便于后续流水线按标准文件名自动查找。2. 异步任务中的字幕生成分支导入任务process_import_taskimport_processing.py接收到srt_file_pathNone时会读取用户配置的语音识别设置get_desktop_config().speech_recognition按配置方法调用generate_subtitle_for_videoif not srt_path: # 使用语音识别生成字幕 generated_subtitle generate_subtitle_for_video( Path(video_path), languagelanguage, # 来自用户配置默认 auto modelmodel, # 来自用户配置默认 base methodspeech_config.method, ... ) srt_path str(generated_subtitle)任务内部还实现了回退机制主方法失败且enable_fallbackTrue时会尝试配置的fallback_method默认whisper_local主方法与回退方法均失败后才将srt_path置为 None 并最终将项目标记为 failedimport_processing.py。若字幕文件最终不存在任务会更新项目状态为 failed 并记录错误字幕文件不存在。3. 识别器核心方法枚举与自动选择底层识别器位于 speech_recognizer.py支持六种识别方法方法值服务可用性检查依据whisper_local本地 faster-whisper / mlx-whisper 运行时whisper_runtime.is_installed()openai_apiOpenAI API环境变量OPENAI_API_KEY非空azure_speechAzure Speech Services同时存在AZURE_SPEECH_KEY与AZURE_SPEECH_REGIONgoogle_speechGoogle Speech-to-TextGOOGLE_APPLICATION_CREDENTIALS指向存在的文件或GOOGLE_SPEECH_API_KEY非空aliyun_speech阿里云语音识别百炼 ASR存在ALIYUN_API_KEY或配置了aliyun_access_keycustom_api自定义 API配置了custom_api_urlcustom_api_key且健康检查通过auto模式按优先级依次探测speech_recognizer.py本地 Whisper → OpenAI → Azure → Google → 阿里云 → 自定义 API取第一个可用者。由于本地 Whisper 免费、离线被列为最高优先级。需要注意本地 Whisper 在桌面端通过设置 → 语音识别按需安装运行时faster-whisper识别时使用int8量化、deviceautoMac 上走 CPU/CTranslate2并开启vad_filter过滤静音段识别结果由内部_segments_to_srt格式化为标准 SRT 时间轴speech_recognizer.py。而 OpenAI、Azure、Google 三个云端服务的实现目前会抛出功能暂未实现请使用本地 Whisper的占位异常speech_recognizer.py实际可用且完整的离线方案是本地 Whisper阿里云百炼qwen3-asr-flash 模型与自定义 API 已有完整调用实现。4. 语言选择策略在识别层语言通过LanguageCode枚举控制AUTO时向 Whisper 传入languageNone由模型自动检测speech_recognizer.pylanguage None if config.language LanguageCode.AUTO else str(config.language).split(-)[0]而在业务层分类与语言的对应关系遵循原文档的策略business/knowledge类优先使用中文识别entertainment及其他类型使用自动检测。前端界面与交互变化对应前端组件 FileUpload.tsx 的改动主要体现在三处1. 上传提示文案更新原文案必须同时导入字幕文件(.srt)改为支持 MP4、AVI、MOV、MKV、WebM 格式可选择导入字幕文件(.srt)或使用AI自动生成见 FileUpload.tsx2. 智能提示仅视频时展示 AI 生成说明当已选视频但未选字幕时界面显示提示FileUpload.tsx{files.video !files.srt ( div将使用AI语音识别自动生成字幕文件/div )}3. 上传校验与请求构造原先视频 字幕 项目名称三者必填的校验简化为仅需视频 项目名称且FormData只在存在字幕文件时才追加srt_file字段// 移除字幕文件必需验证 if (!files.video) { message.error(请选择视频文件) return } const formData new FormData() formData.append(video_file, data.video_file) if (data.srt_file) { // 只在有字幕文件时才添加 formData.append(srt_file, data.srt_file) }前端还增强了错误分级提示FileUpload.tsx413 提示文件过大、415 提示格式不支持、400 直接展示后端detail如语音识别失败信息、500 提示服务器处理异常等。语音识别服务配置要求要使用仅上传视频模式必须至少配置一种可用的语音识别服务。1. 本地 Whisper推荐离线、免费、无需 API 密钥是默认与回退的首选。桌面端可在设置 → 语音识别中直接安装运行时并下载模型命令行环境也可通过 pip 安装pip install openai-whisper # macOS brew install ffmpeg # Ubuntu/Debian sudo apt install ffmpegWhisper 模型档位来源于 speech_recognition.py 的官方建议模型大小速度准确率适用场景tiny39 MB最快较低实时处理、快速预览base74 MB快中等日常使用、平衡选择默认small244 MB中等较好重要内容、知识类视频medium769 MB较慢高专业用途、演讲内容large1550 MB最慢最高重要项目、最高质量要求2. 云端服务通过环境变量# OpenAI API export OPENAI_API_KEYyour-api-key # Azure Speech Services export AZURE_SPEECH_KEYyour-api-key export AZURE_SPEECH_REGIONyour-region # Google Speech-to-Text export GOOGLE_APPLICATION_CREDENTIALSpath/to/credentials.json # 阿里云语音识别 export ALIYUN_ACCESS_KEY_IDyour-access-key export ALIYUN_ACCESS_KEY_SECRETyour-secret-key export ALIYUN_SPEECH_APP_KEYyour-app-key阿里云识别通过百炼 DashScope 接口https://dashscope.aliyuncs.com/api/v1/services/aigc/audio/asr提交 base64 音频并直接请求 SRT 输出speech_recognizer.py。检查配置状态原文档描述的GET /api/v1/speech-recognition/status端点在当前仓库中由 speech_recognition.py 提供的一组端点替代实际可用GET /api/v1/speech-recognition/config获取当前语音识别完整配置各服务的 key、语言、时间戳开关等GET /api/v1/speech-methods-status逐项返回各方法的可用状态与缺失原因提示如需要安装Whisper需要配置OpenAI API KeyGET /api/v1/whisper-models列出 Whisper 各模型的下载/可用状态POST /api/v1/speech-recognition/validate校验配置并返回 errors/warnings/recommendationsPOST /api/v1/test-speech-service测试指定识别服务是否可用。例如用 curl 快速探测curl http://localhost:8000/api/v1/speech-methods-status返回示例各方法可用性布尔值与提示信息[ {method: whisper_local, available: true, message: null}, {method: openai_api, available: false, message: 需要配置OpenAI API Key}, {method: aliyun_speech, available: false, message: 需要配置阿里云API Key} ]配置参数速查表SpeechRecognitionConfigspeech_recognizer.py中值得关注的参数及默认值参数默认值说明methodwhisper_local识别方法可选whisper_local/openai_api/azure_speech/google_speech/aliyun_speech/custom_apilanguageauto识别语言auto为自动检测modelbaseWhisper 模型仅对本地模式生效合法值 tiny/base/small/medium/largetimeout0无限制超时秒数前端配置默认 1800 秒30 分钟output_formatsrt输出格式支持 srt/vtt/txt/jsonenable_timestampsTrue是否启用时间戳enable_punctuationTrue是否启用标点enable_speaker_diarizationFalse说话人分离会增加处理时间enable_fallbackTrue是否启用回退机制fallback_methodwhisper_local回退方法这些参数均可通过PUT /api/v1/speech-recognition/config持久化到桌面配置并会被导入任务实时读取import_processing.py。最佳实践1. 用户体验优化清晰提示明确告知用户字幕文件是可选的同时展示将使用AI语音识别自动生成字幕文件的预期说明处理时间告知用户语音识别可能耗时较长首次运行还需下载模型项目会在后台异步处理可随时查看进度错误恢复识别失败时给出可操作建议安装 Whisper / 配置 API 密钥 / 手动补传字幕并提供重新处理入口。2. 性能考虑模型选择默认使用base模型平衡速度与准确率首次使用建议先下载 base 进行测试重要内容再升级到 small/medium语言优化根据视频分类指定识别语言知识/商业类用中文可显著提升准确率与速度auto模式适合多语言或不确定内容超时设置合理设置超时默认 30 分钟长视频建议分段处理或换用更快模型降级策略保持enable_fallbackTrue让主方法失败时自动回退到本地 Whisper。3. 错误处理服务检查上传/导入时检查语音识别服务可用性SpeechRecognizer.__init__即会探测全部方法降级顺序auto模式按本地 Whisper → 云端 → 自定义优先级依次尝试用户友好400 响应携带中文可读的 detail前端直接展示并给出下一步建议。故障排除常见问题1. 没有可用的语音识别服务检查是否安装了 Whisperwhich whisper或pip list | grep whisper检查是否配置了 API 密钥环境变量查看服务状态GET /api/v1/speech-methods-status确认各方法可用性。2. 语音识别超时检查视频文件大小建议 100MB增加超时设置timeout参数尝试更快的模型tiny/base。3. 字幕文件不存在确认 Whisper 运行时已安装且模型已下载查看后端日志了解详细错误导入任务失败会在任务状态中记录具体异常手动运行 Whisper 测试。调试步骤# 1. 检查语音识别服务状态 curl http://localhost:8000/api/v1/speech-methods-status # 2. 查看后端日志 tail -f backend/backend.log # 3. 测试 Whisper 与 FFmpeg 安装 whisper --help ffmpeg -version更新日志摘要v1.0.0支持可选 SRT 文件上传srt_file变为可选参数集成多种语音识别服务本地 Whisper、OpenAI、Azure、Google、阿里云、自定义 API智能语言选择按视频分类自动切换识别语言完善的错误处理与用户友好提示支持回退机制与配置校验/建议接口。相关文档语音识别重新设计文档语音识别设置指南后端架构文档系统架构文档快速入门指南赞分享音视频AI 应用后端前端【免费下载链接】autoclipAutoClip : AI-powered video clipping and highlight generation · 一款智能高光提取与剪辑的二创工具项目地址https://gitcode.com/GitHub_Trending/autoc/autoclip点击查看免费下载相关推荐Video-SRT-Windows智能视频字幕生成完整解决方案Video SRT Windows智能视频字幕生成完整解决方案 在视频内容爆发的数字时代高效的字幕生成技术已成为内容创作者的必备利器。传统手动字幕制作平均每语音音频人工智能解决遮挡难题Extreme 3D Faces如何让3D人脸重建突破视觉障碍解决遮挡难题Extreme 3D Faces如何让3D人脸重建突破视觉障碍 Extreme 3D Faces是一个专注于从单张图像实现 3D人脸重建 的开源FunClip字幕生成功能详解自动创建SRT字幕的完整指南FunClip字幕生成功能详解自动创建SRT字幕的完整指南 FunClip作为一款开源、精准且易于使用的视频语音识别与剪辑工具其强大的 字幕生成功能 让视频音视频语音人工智能AI 应用本地部署创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考