Subtitle 字幕配置

字幕功能支持单词级别的时间戳同步和高亮效果，适合制作带字幕的视频内容。

数据结构

SubtitleWord 单词数据

interface SubtitleWord {
  word: string;           // 原始单词
  punctuated_word: string; // 带标点的单词（用于显示）
  start: number;           // 开始时间（秒）
  end: number;             // 结束时间（秒）
  confidence?: number;     // 语音识别置信度 0-1
}

SubtitleClip 字幕片段

interface SubtitleClip extends BaseClip {
  type: 'subtitle';
  words: SubtitleSource;  // 字幕数据源
  config?: SubtitleConfig; // 字幕配置
}

SubtitleSource 数据源

支持三种格式：

type SubtitleSource =
  | SubtitleWord[]        // 内联数据
  | { $ref: string }      // 引用 assets 中的资源
  | { src: string };      // 外部 URL

字幕配置

interface SubtitleConfig {
  mode?: 'batch' | 'stream';     // 显示模式
  wordsPerBatch?: number;        // 批量模式每批词数，默认 4
  fontSize?: number;             // 字体大小，默认 80
  fontFamily?: string;           // 字体，默认 Arial
  fontWeight?: number | string;  // 字重，默认 800
  textAlign?: 'left' | 'center' | 'right';
  textBoxWidth?: number | string; // 文本框宽度，默认 "70%"
  textColor?: string;            // 文字颜色，默认 #ffffff
  highlightColor?: string;       // 当前词高亮颜色，默认 #00ffff
  backgroundColor?: string;      // 高亮背景色
  shadowColor?: string;          // 阴影颜色，默认 #000000
  shadowBlur?: number;           // 阴影模糊，默认 30
  borderColor?: string;          // 描边颜色
  borderWidth?: number;          // 描边宽度
  fadeInAnimation?: boolean;     // 是否启用淡入动画，默认 true
  position?: 'bottom' | 'top' | 'center'; // 字幕位置
  paddingBottom?: number;        // 底部间距，默认 150
}

显示模式

批量模式 (batch)

每批显示 N 个单词，当前朗读的单词会高亮显示。

{
  "type": "subtitle",
  "words": [...],
  "config": {
    "mode": "batch",
    "wordsPerBatch": 4
  }
}

流式模式 (stream)

单词逐个出现，每个单词独立显示。

{
  "type": "subtitle",
  "words": [...],
  "config": {
    "mode": "stream"
  }
}

完整示例

内联数据

{
  "tracks": [
    {
      "id": "subtitle-track",
      "type": "subtitle",
      "clips": [
        {
          "id": "main-subtitle",
          "type": "subtitle",
          "start": 0,
          "duration": 10,
          "words": [
            { "word": "welcome", "punctuated_word": "Welcome", "start": 0.5, "end": 1.0 },
            { "word": "to", "punctuated_word": "to", "start": 1.0, "end": 1.2 },
            { "word": "the", "punctuated_word": "the", "start": 1.2, "end": 1.4 },
            { "word": "future", "punctuated_word": "future", "start": 1.4, "end": 2.0 }
          ],
          "config": {
            "mode": "batch",
            "wordsPerBatch": 4,
            "fontSize": 80,
            "highlightColor": "#00ffff",
            "backgroundColor": "#e94560",
            "shadowBlur": 30
          }
        }
      ]
    }
  ]
}

资源引用

{
  "assets": {
    "subtitles": [
      {
        "id": "main-subtitle",
        "words": [
          { "word": "hello", "punctuated_word": "Hello", "start": 0, "end": 0.5 }
        ]
      }
    ]
  },
  "tracks": [
    {
      "type": "subtitle",
      "clips": [
        {
          "type": "subtitle",
          "start": 0,
          "duration": 10,
          "words": { "$ref": "main-subtitle" }
        }
      ]
    }
  ]
}

配置说明

字段	类型	默认值	描述
mode	string	'batch'	显示模式：batch 或 stream
wordsPerBatch	number	4	批量模式每批显示的单词数
fontSize	number	80	字体大小
fontFamily	string	'Arial'	字体
fontWeight	number/string	800	字重
textAlign	string	'center'	对齐方式
textBoxWidth	number/string	'70%'	文本框宽度
textColor	string	'#ffffff'	文字颜色
highlightColor	string	'#00ffff'	当前词高亮颜色
backgroundColor	string	''	高亮背景色
shadowColor	string	'#000000'	阴影颜色
shadowBlur	number	30	阴影模糊度
borderColor	string	''	描边颜色
borderWidth	number	0	描边宽度
fadeInAnimation	boolean	true	是否启用淡入动画
position	string	'bottom'	字幕位置
paddingBottom	number	150	底部间距

数据来源

字幕数据通常来自语音识别服务（如 AssemblyAI），包含精确到毫秒级的单词时间戳。

语音识别输出格式

{
  "word": "hello",
  "start": 0.08,
  "end": 0.39999998,
  "confidence": 0.9988054,
  "punctuated_word": "Hello"
}

最佳实践

批量模式：适合常规字幕显示，建议每批 3-5 个单词
流式模式：适合打字机效果或强调单个词
高亮颜色：使用与主题色协调的高亮颜色
阴影效果：确保字幕在各种背景下清晰可见
数据准备：使用语音识别服务获取精确的时间戳数据
与音频同步：字幕的 words 数据应与语音音频配套使用

Subtitle 字幕配置

On this page