> ## Documentation Index
> Fetch the complete documentation index at: https://typecast.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 타임스탬프와 자막

CLI는 타입캐스트 Timestamp TTS를 호출해 생성된 오디오와 함께 정렬 데이터를 저장할 수 있습니다. 쇼츠 자막, 소셜 영상 캡션 타이밍, 가라오케 스타일 하이라이트, 립싱크 메타데이터가 필요할 때 사용합니다.

## 자막 생성

```bash
# 오디오와 SRT 자막 저장
cast "Hello, world. This is a test." \
  --out hello.wav \
  --timestamp-out hello.srt

# 오디오와 WebVTT 자막 저장
cast "Hello, world. This is a test." \
  --out hello.wav \
  --timestamp-out hello.vtt \
  --timestamp-format vtt
```

`--timestamp-format`을 생략하면 CLI는 `--timestamp-out` 확장자에서 `srt` 또는 `vtt`를 추론하고, 그렇지 않으면 `json`으로 저장합니다.

템포나 무음 길이를 조절하면 타임스탬프는 처리 후 오디오를 기준으로 반환됩니다. 제거된 무음을 차감하거나 자막 시간을 다시 보정하지 마세요. 옵션 사용법은 [설정](/docs/ko/cli-reference/configuration)을 참조하세요.

## 원본 타임스탬프 JSON 저장

```bash
cast "Hello, world. This is a test." \
  --out hello.wav \
  --timestamp-out hello.timestamps.json
```

JSON은 다른 도구가 자막을 만들거나, 텍스트 애니메이션을 렌더링하거나, 시각 요소를 직접 정렬해야 할 때 유용합니다.

## 자막 출력 단위 선택

Cast v1.0.12 이상에서는 SRT와 WebVTT에 `--caption-unit sentence|word|char`를 사용할 수 있습니다. 기본값은 `sentence`입니다. 단어마다 자막을 표시하려면 `word`, 문자마다 표시하려면 `char`를 선택하세요.

```bash
cast "Hello, world. This is a test." \
  --out hello.wav \
  --timestamp-out hello.srt \
  --caption-unit word
```

`--timestamp-granularity`는 API가 반환할 정렬 데이터를 선택하고, `--caption-unit`는 그 데이터를 자막 구간으로 만드는 단위를 선택합니다. `--timestamp-granularity`를 생략하면 단어·문자 자막은 필요한 정렬 단위를 자동 요청합니다. 명시할 때는 자막 단위와 일치하거나 `both`여야 합니다. 원본 JSON 구조는 유지되며, JSON 출력에는 `--caption-unit word`나 `char`를 사용하지 마세요. 일본어(`jpn`)나 중국어(`zho`)에는 `--caption-unit char`를 사용하세요.

## Granularity 선택

```bash
cast "Hello, world." \
  --out hello.wav \
  --timestamp-out hello.srt \
  --timestamp-granularity both
```

일본어(`jpn`)나 중국어(`zho`)처럼 단어 사이 공백이 없는 언어는 문자 단위 타임스탬프가 자막 타이밍에 더 적합합니다:

```bash
cast "こんにちは。世界。" \
  --language jpn \
  --out hello.wav \
  --timestamp-out hello.srt
```

## 에이전트용 자막 워크플로우

```text
script.txt에서 내레이션 오디오와 자막을 만들어줘.
CLI를 사용해줘.
오디오는 ./video/voiceover.wav에 저장해줘.
자막은 ./video/voiceover.srt에 저장해줘.
자막 파일은 오디오 파일 옆에 둬.
```

## 출력 선택

| 출력 | 사용 시점 |
|------|-----------|
| `.srt` | 영상 편집기, Shorts/Reels/TikTok 자막 import |
| `.vtt` | 웹 비디오 플레이어와 브라우저 기반 preview |
| `.json` | 커스텀 렌더링, 가라오케 하이라이트, 립싱크, 후속 자동화 |

<Tip>
  소셜 영상에서는 오디오와 자막을 같은 단계에서 생성하세요. 최종 내레이션과 자막 타이밍이 같은 합성 결과에 묶입니다.
</Tip>