# Untertitel-Element

## 1. Struktur

```ts
type SubtitleSource =
  | SubtitleWord[]
  | { $ref: string }
  | { src: string };

interface SubtitleClip extends BaseClip {
  type: "subtitle";
  words: SubtitleSource;
  config?: SubtitleConfig;
}
```

Unterstützt außerdem:
- `opacity`
- `animations`
- `keyframes`
- `transition`
- `transform`
- `zIndex`

## 2. `SubtitleWord`

```ts
interface SubtitleWord {
  word: string;
  punctuated_word: string;
  start: number;
  end: number;
  confidence?: number;
}
```

## 3. Unterstützte Untertitelquellen

### Inline-Array

```json
{
  "words": [
    {
      "word": "hello",
      "punctuated_word": "Hello",
      "start": 0,
      "end": 0.4
    }
  ]
}
```

### Untertitel-Asset über `$ref`

```json
{
  "words": { "$ref": "subtitle-main" }
}
```

### Externe URL

```json
{
  "words": { "src": "https://example.com/subtitle.json" }
}
```

## 4. Regeln für externe Untertitel-URLs

Der Remote-Endpunkt muss JSON in einer dieser Formen zurückgeben:
- `SubtitleWord[]`
- `{ "words": SubtitleWord[] }`

Öffentliches Verhalten:
- Der Preview-Flow akzeptiert `words: { "src": "..." }`
- Die Preview-Wiedergabe normalisiert die Untertiteldaten vor der Wiedergabe
- Wenn du `{ src }` direkt an einen niedrigeren Renderer sendest, werden die Untertiteldaten nicht automatisch geladen

## 5. `SubtitleConfig`

```ts
interface SubtitleConfig {
  mode?: "batch" | "stream";
  wordsPerBatch?: number;
  fontSize?: number;
  fontFamily?: string;
  fontWeight?: number | string;
  textAlign?: "left" | "center" | "right";
  textBoxWidth?: number | string;
  textColor?: string;
  highlightColor?: string;
  backgroundColor?: string;
  shadowColor?: string;
  shadowBlur?: number;
  borderColor?: string;
  borderWidth?: number;
  fadeInAnimation?: boolean;
  position?: "bottom" | "top" | "center";
  paddingBottom?: number;
}
```

## 6. Derzeit implementierte Konfigurationsfelder

- `mode`
- `wordsPerBatch`
- `fontSize`
- `fontFamily`
- `fontWeight`
- `textAlign`
- `textBoxWidth`
- `textColor`
- `highlightColor`
- `backgroundColor`
- `shadowColor`
- `shadowBlur`
- `borderColor`
- `borderWidth`
- `fadeInAnimation`
- `position`
- `paddingBottom`

## 7. Verhalten der Modi

### `batch`
- Zeigt Untertitel in Blöcken an
- Hebt das aktuell gesprochene Wort hervor

### `stream`
- Blendet Wörter nacheinander ein

## 8. Animationsverhalten des gesamten Blocks

Die Animation auf Container-Ebene wirkt auf den gesamten Untertitelblock, nicht auf die Hervorhebungslogik einzelner Wörter.

Wichtiger Unterschied:
- `config.fadeInAnimation` steuert das Fade-Verhalten innerhalb von Untertitelblöcken
- `animations / keyframes / transition` steuern den gesamten Untertitel-Container

Das bedeutet, du kannst den Untertitelblock selbst mit Fade, Slide oder Bewegung animieren, ohne die interne Wort-Hervorhebungslogik zu verändern.

## 9. Beispiel

```json
{
  "type": "subtitle",
  "start": 0,
  "duration": 8,
  "words": { "$ref": "sub-main" },
  "animations": [
    { "type": "slideIn", "duration": 0.4, "direction": "up" }
  ],
  "config": {
    "position": "bottom",
    "fontSize": 60,
    "highlightColor": "#22d3ee",
    "backgroundColor": "rgba(0,0,0,0.4)"
  }
}
```