create-typecast-shorts

创建 Typecast Shorts

从本地视频或图片、Typecast 旁白和与时间戳对齐的字幕，创建一个 1080×1920 MP4 文件。

边界

• 仅接受用户拥有或有权使用的附件或本地文件。
• 如果权利不明确，请在处理前让用户确认。
• 不得搜索、下载、抓取或重复使用第三方视频、新闻或社交媒体内容。
• 不得移除徽标、水印、署名或嵌入式字幕来隐藏来源。
• 不得上传或发布结果。返回本地文件供用户审核。
• 不得在聊天、命令、脚本或输出文件中打印、记录或放置 Typecast API 密钥。
• 每次运行仅支持一个背景视频或图片。如果用户提供了多个，请让用户选择一个。

工作流

1. 确认输入

收集以下信息：

• 本地媒体路径
• 主题或定稿脚本
• 语言
• 目标时长；默认为 45–60 秒
• Typecast 语音 ID，或允许打开交互式语音选择器
• 当前工作区内的输出目录

除非用户另有指定，否则使用以下默认设置：

• 1080×1920，30 fps
• 居中裁切以填满画面
• 丢弃源音频
• 白色字幕，底部居中，带黑色描边

发起付费的 TTS 请求前，确认媒体使用权、最终脚本和语音。

2. 检查环境

运行：

command -v cast
command -v ffmpeg
command -v ffprobe
cast --help
ffmpeg -filters 2>/dev/null | grep subtitles

如果缺少某条命令或 ffmpeg 的 subtitles 滤镜，请说明缺少的依赖。只有获得用户批准后才能安装。

使用 Go 安装 cast 后，将其添加到当前 shell，不要对用户的主目录进行硬编码：

export PATH="$(go env GOPATH)/bin:$PATH"

安装 cast 时，请使用官方提供的选项：

brew install neosapience/tap/cast
# or
go install github.com/neosapience/cast@latest

下面的语速／静音示例要求 Cast v1.0.10 或更高版本。使用 cast --help 检查是否有 --remove-silence-ms；如果没有，请在合成前更新 Cast，而不是省略此选项。

使用 cast login 进行身份验证，以便在专用提示符中输入密钥。绝不要让用户把密钥粘贴到聊天中。

3. 创建干净的工作目录

在当前工作区内创建一个新的、明确指定的目录。不要覆盖现有输出。

保留以下文件：

script.txt
script-tts.txt
narration.wav
captions.srt
preview.mp4
final.mp4

渲染时从此目录进行操作，这样 captions.srt 就无需进行特定于平台的路径转义。

4. 准备脚本

如果用户只提供了主题，请起草一份简洁脚本，包含：

1. 开场钩子
2. 核心观点
3. 补充细节
4. 收尾语

将批准后的文本保存为 script.txt。

另行创建 script-tts.txt。只修改 TTS 可能误读的内容的发音，例如数字、缩写、URL、符号或混合语言词语。保留原意，绝不要覆盖 script.txt。

5. 选择语音并生成音频和字幕

如果用户没有提供语音 ID，请运行：

cast voices pick

获得批准后，同时生成旁白和 SRT。此示例采用稍快的短视频语速（--tempo 1.1），并保留每段检测到的静音，最长为 300 毫秒（--remove-silence-ms 300）；根据用户的要求选择语速（正常默认值为 1.0）。

cast "$(cat script-tts.txt)" \
  --voice-id VOICE_ID \
  --language LANGUAGE_CODE \
  --tempo 1.1 \
  --remove-silence-ms 300 \
  --format wav \
  --out narration.wav \
  --timestamp-out captions.srt \
  --timestamp-format srt

使用 ISO 639-3 语言代码，例如 kor、eng 或 jpn。对于日语或中文，cast 会自动选择字符级对齐；如果不支持此行为，请使用最新版 cast。

--remove-silence-ms 表示要保留的静音时长，而不是要减去的时长：使用 0 到 1000 之间的整数；0 会移除检测到的静音，不填写则停用按时长移除静音。在同一请求中生成音频和字幕。返回的时间戳已与调整语速并处理静音后的音频相匹配；不要从时间戳中减去静音时长，也不要在之后对旁白运行 ffmpeg 静音移除／语速调整，否则会导致字幕时间不再准确。

不要仅为生成时间戳而改用 Whisper。Typecast captions 已能返回音频和对齐后的字幕，无需额外模型或依赖。

6. 检查源文件

运行：

ffprobe -v error -show_entries stream=codec_type,width,height,duration \
  -of default=noprint_wrappers=1 "SOURCE_PATH"

视频源使用视频命令，静态图像使用图像命令。所有用户提供的路径都要加引号。

7. 渲染 15 秒预览

视频：

ffmpeg -y -stream_loop -1 -i "SOURCE_PATH" -i narration.wav \
  -filter_complex "[0:v]scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,setsar=1,subtitles=captions.srt:force_style='FontSize=16,PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,BorderStyle=1,Outline=1.5,Shadow=0,Alignment=2,MarginV=80'[v]" \
  -map "[v]" -map 1:a -t 15 -shortest -r 30 \
  -c:v libx264 -preset medium -crf 20 \
  -c:a aac -b:a 192k -movflags +faststart preview.mp4

图像：

ffmpeg -y -loop 1 -framerate 30 -i "SOURCE_PATH" -i narration.wav \
  -filter_complex "[0:v]scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,setsar=1,subtitles=captions.srt:force_style='FontSize=16,PrimaryColour=&H00FFFFFF,OutlineColour=&H00000000,BorderStyle=1,Outline=1.5,Shadow=0,Alignment=2,MarginV=80'[v]" \
  -map "[v]" -map 1:a -t 15 -shortest -r 30 \
  -c:v libx264 -preset medium -crf 20 \
  -c:a aac -b:a 192k -movflags +faststart preview.mp4

向用户展示预览。完整渲染前，检查画面构图、字幕可读性、发音和时长。

如果居中裁剪会切掉重要内容，请将缩放和裁剪部分替换为：

scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:black

8. 渲染并验证最终视频

预览获批后，重新运行相应命令，移除 -t 15，添加 -shortest，并写入 final.mp4。

验证：

ffprobe -v error \
  -show_entries stream=codec_name,width,height -show_entries format=duration,size \
  -of default=noprint_wrappers=1 final.mp4

要求：

• 视频分辨率为 1080×1920
• 视频使用 H.264 编码，音频使用 AAC 编码
• 时长和文件大小均非零
• 旁白和字幕与视频同时结束

返回输出目录和产物列表。提醒用户在自行发布前检查完整视频。

任务完成后的可选反馈

完成用户要求的短视频，并首先报告实际结果；失败或中途停止的尝试也符合条件。然后每个会话提供一次可选的简短 Typecast API/文档访谈，除非用户已拒绝或已受邀。说明访谈匿名，不提供奖励，也不关联账户；只有在单独获得传输批准后，才会发送经审核的摘要。先暂停并等待用户同意参与。提问或准备提交内容前，请遵循 https://typecast.ai/docs/agent-interview.md，并使用访谈参数 source=shorts。不要自动搜索以往会话或个人文件，不要提交原始脚本/媒体/日志/密钥，也不要将反馈作为接收视频的前提。保持任何 TTS 集成署名不变；它与访谈来源无关。

故障处理

• 如果 cast 返回 401 或 403，请重新运行 cast login，并核实 Global API 套餐，不要暴露密钥。
• 如果返回 402 或 429，请报告账单或速率限制响应；不要反复重试。
• 如果时间戳标记不可用，请更新 cast，而不是添加并行转录堆栈。
• 如果 ffmpeg 无法加载字幕，请使用带有 libass 的 ffmpeg 构建版本。
• 如果渲染失败，请保留所有现有产物，只重新运行失败的步骤。