> ## 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.

# 음성 생성

## 기능 맵

| 필요 | 사용 |
|------|------|
| 즉시 로컬 재생 | `cast "text"` |
| 재사용 가능한 오디오 파일 | `--out file.wav` 또는 `--out file.mp3 --format mp3` |
| 에이전트의 실시간 느낌 응답 | `--out` 없이 기본 재생 |
| 타임스탬프 JSON | `--timestamp-out file.json` |
| SRT 또는 WebVTT 자막 | `--timestamp-out file.srt` 또는 `--timestamp-out file.vtt` |
| 클로닝한 커스텀 보이스 | `cast voices clone` 후 `--voice-id uc_xxx` |

## 기본 사용법

```bash
# 바로 재생
cast "Hello, world!"

# 특정 보이스 사용
cast "Hello, world!" --voice-id tc_xxx

# WAV 파일로 저장
cast "Hello, world!" --out hello.wav

# MP3 파일로 저장
cast "Hello, world!" --out hello.mp3 --format mp3

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

기본적으로 `cast`는 오디오를 즉시 재생합니다. `--out`을 사용하면 WAV 또는 MP3 파일로 저장할 수 있습니다.

<Info>
  로컬 에이전트가 빠르게 말해야 하는 상황에서는 `--out` 없이 바로 재생하는 방식이 가장 단순합니다. API 레벨의 chunked streaming(`POST /v1/text-to-speech/stream`)은 [Streaming TTS](/ko/quickstart#실시간-오디오-스트리밍)와 SDK 문서를 참고하세요.
</Info>

## 옵션

| 플래그 | 설명 | 기본값 |
|--------|------|--------|
| `--voice-id` | Voice ID | `tc_60e5426de8b95f1d3000d7b5` |
| `--model` | 모델 (`ssfm-v30`, `ssfm-v21`) | `ssfm-v30` |
| `--language` | 언어 코드 (ISO 639-3) | 자동 감지 |
| `--emotion` | 감정 유형: `smart`, `preset` | |
| `--emotion-preset` | 이모션 프리셋 (`--emotion preset` 필요) | |
| `--emotion-intensity` | 감정 강도 0.0-2.0 (`--emotion preset` 필요) | `1.0` |
| `--prev-text` | 문맥을 위한 이전 문장 (`--emotion smart` 전용) | |
| `--next-text` | 문맥을 위한 다음 문장 (`--emotion smart` 전용) | |
| `--volume` | 볼륨 (0-200) | `100` |
| `--pitch` | 피치 (반음 단위, -12 ~ +12) | `0` |
| `--tempo` | 템포 배율 (0.5-2.0) | `1.0` |
| `--remove-silence-ms` | 남길 무음 길이(정수 0–1000ms). 0은 검출된 무음 제거 | 미설정 |
| `--format` | 출력 형식 (`wav`, `mp3`) | `wav` |
| `--out` | 재생 대신 파일로 저장 | |
| `--timestamp-out` | 타임스탬프 출력을 JSON, SRT, WebVTT로 저장 | |
| `--timestamp-format` | 타임스탬프 출력 형식 (`json`, `srt`, `vtt`) | `--timestamp-out`에서 추론 |
| `--timestamp-granularity` | 타임스탬프 단위 (`word`, `char`, `both`) | 서버 기본값 |

## 모델

| 모델 | 언어 | 감정 | 지연시간 |
|------|------|------|----------|
| `ssfm-v30` | 35+개 | 7개 프리셋 + 스마트 이모션 | 표준 |
| `ssfm-v21` | 27개 | 4개 프리셋: normal, happy, sad, angry | 낮음 |

```bash
cast "Hello, world!" --model ssfm-v21
```

## 감정

<Tabs>
  <Tab title="스마트 이모션">
    AI가 텍스트에서 적절한 감정을 자동으로 추론합니다. 스마트 이모션은 `ssfm-v30`에서 사용할 수 있습니다.

    ```bash
    cast "I just got promoted!" --emotion smart
    ```

    더 나은 문맥을 위해 앞뒤 문장을 제공할 수 있습니다:

    ```bash
    cast "I just got promoted!" --emotion smart \
      --prev-text "I have been working so hard this year." \
      --next-text "Let's celebrate tonight!"
    ```
  </Tab>
  <Tab title="이모션 프리셋">
    `--emotion-preset`으로 특정 감정을 선택하고 `--emotion-intensity`로 강도를 제어합니다.

    | 모델 | 사용 가능한 프리셋 |
    |------|-------------------|
    | `ssfm-v30` | `normal`, `happy`, `sad`, `angry`, `whisper`, `toneup`, `tonedown` |
    | `ssfm-v21` | `normal`, `happy`, `sad`, `angry` |

    ```bash
    cast "Hello, world!" --emotion preset --emotion-preset happy
    cast "Hello, world!" --emotion preset --emotion-preset happy --emotion-intensity 2.0
    cast "Hello, world!" --emotion preset --emotion-preset whisper --emotion-intensity 0.5
    cast "Hello, world!" --model ssfm-v21 --emotion preset --emotion-preset sad
    ```
  </Tab>
</Tabs>

## 무음 길이 조절

**Cast v1.0.10 이상**에서 `--remove-silence-ms`로 설정합니다. 기본값은 미설정이며 `0`이 아닙니다.

```bash
cast "Hello. Thank you for listening." --voice-id tc_672c5f5ce59fac2a48faeaee --remove-silence-ms 300
```

`remove_silence_ms`는 제거할 시간이 아니라 **남길 무음 길이**를 지정합니다. `0`부터 `1000`ms까지의 정수를 사용하세요. `0`은 검출된 무음을 제거하며, 생략하거나 `null`을 지정하면 지정 길이에 따른 무음 제거를 적용하지 않습니다.

일반·스트리밍·타임스탬프 TTS는 `output.remove_silence_ms`, Compose는 각 `tts` 세그먼트의 `segments[].output.remove_silence_ms`로 전달합니다. 반환 타임스탬프는 처리 후 오디오를 기준으로 하며, 명시적인 `pause` 세그먼트는 유지됩니다.

스트리밍의 기본 앞부분 무음 트림은 별개입니다. 특히 `0`처럼 작은 값에서는 재생 가능한 청크 수신에 간격이 생길 수 있으므로 충분한 재생 버퍼를 확보하고 실제 콘텐츠로 확인하세요.