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

# Java

> 공식 Java SDK로 타입캐스트 API에 액세스하세요.

[타입캐스트 API](https://typecast.ai)를 위한 공식 Java 라이브러리입니다. AI 기반 음성을 사용하여 텍스트를 생동감 있는 음성으로 변환하세요.

Java 8 이상 버전과 호환됩니다. Maven, Gradle, 수동 설치와 함께 작동합니다.

<CardGroup cols={2}>
  <Card title="Maven Central" icon="cube" href="https://central.sonatype.com/artifact/com.neosapience/typecast-java">
    Typecast Java SDK
  </Card>

  <Card title="소스 코드" icon="github" href="https://github.com/neosapience/typecast-sdk/tree/main/typecast-java">
    Typecast Java SDK 소스 코드
  </Card>
</CardGroup>

## 설치

<Tabs>
  <Tab title="Maven">
    `pom.xml`에 다음 의존성을 추가하세요:

    ```xml theme={null}
    <dependency>
        <groupId>com.neosapience</groupId>
        <artifactId>typecast-java</artifactId>
        <version>1.2.7</version>
    </dependency>
    ```
  </Tab>

  <Tab title="Gradle">
    `build.gradle`에 추가하세요:

    ```groovy theme={null}
    implementation 'com.neosapience:typecast-java:1.2.7'
    ```
  </Tab>

  <Tab title="수동">
    로컬 Maven 저장소에 클론하고 설치하세요:

    ```bash theme={null}
    git clone https://github.com/neosapience/typecast-sdk.git
    cd typecast-sdk/typecast-java
    mvn clean install -DskipTests
    ```
  </Tab>
</Tabs>

<Warning>
  최신 등록 버전은 Maven Central 기준 **1.2.7**입니다. **버전 1.2.7 이상**이 설치되어 있는지 확인하세요. 이전 버전이 있다면 `pom.xml` 또는 `build.gradle`에서 의존성 버전을 업데이트하세요.
</Warning>

## 빠른 시작

```java theme={null}
import com.neosapience.TypecastClient;
import com.neosapience.models.*;

import java.io.FileOutputStream;

public class QuickStart {
    public static void main(String[] args) throws Exception {
        // 클라이언트 초기화
        TypecastClient client = new TypecastClient("YOUR_API_KEY");

        // 텍스트를 음성으로 변환
        TTSRequest request = TTSRequest.builder()
                .voiceId("tc_672c5f5ce59fac2a48faeaee")
                .text("안녕하세요! 저는 텍스트 음성 변환 에이전트입니다.")
                .model(TTSModel.SSFM_V30)
                .build();

        TTSResponse response = client.textToSpeech(request);

        // 오디오 파일 저장
        try (FileOutputStream fos = new FileOutputStream("output." + response.getFormat())) {
            fos.write(response.getAudioData());
        }

        System.out.println("Audio saved! Duration: " + response.getDuration() + "s, Format: " + response.getFormat());

        // 정리
        client.close();
    }
}
```

## 기능

Typecast Java SDK는 텍스트 음성 변환을 위한 강력한 기능을 제공합니다:

* **다중 음성 모델**: `ssfm-v30`(최신) 및 `ssfm-v21` AI 음성 모델 지원
* **다국어 지원**: 영어, 한국어, 스페인어, 일본어, 중국어 등 37개 언어 지원
* **감정 제어**: 이모션 프리셋(normal, happy, sad, angry, whisper, toneup, tonedown) 또는 스마트 문맥 인식 추론
* **오디오 사용자 정의**: 라우드니스 LUFS(-70 to 0), 피치(-12 to +12 반음), 템포(0.5x to 2.0x), 형식(WAV/MP3) 제어
* **음성 탐색**: 모델, 성별, 나이, 사용 사례별 필터링이 가능한 V2 Voices API
* **빌더 패턴**: 쉬운 요청 구성을 위한 빌더 패턴의 Fluent API
* **타임스탬프 TTS**: 자막, 가라오케, 립싱크를 위한 단어·문자 단위 정렬 데이터
* **스트리밍**: 저지연 재생을 위한 실시간 청크 오디오 전송
* **포괄적인 오류 처리**: 각 오류 유형에 대한 특정 예외 클래스

## 보이스 추천

원하는 스타일은 알지만 정확한 `voice_id`를 모를 때 `recommendVoices`를 사용합니다.

```java theme={null}
List<RecommendedVoice> voices = client.recommendVoices(
    "warm female voice for a product tutorial",
    3
);

for (RecommendedVoice voice : voices) {
    System.out.println(voice.getVoiceId() + " " + voice.getVoiceName() + " " + voice.getScore());
}
```

추천 결과에는 `voiceId`, `voiceName`, `score`만 포함됩니다. 지원 모델, 감정, 성별, 연령대, 사용 사례 같은 상세 메타데이터가 필요하면 `getVoiceV2` 또는 `getVoicesV2`로 추가 조회하세요.

## 구성

환경 변수, `.env` 파일 또는 생성자를 통해 API 키를 설정하세요:

```java theme={null}
// 환경 변수 사용
// export TYPECAST_API_KEY="your-api-key-here"
TypecastClient client = new TypecastClient();

// 또는 직접 전달
TypecastClient client = new TypecastClient("your-api-key-here");

// 또는 사용자 정의 base URL과 함께
TypecastClient client = new TypecastClient("your-api-key-here", "https://custom-api.example.com");
```

<Info>
  자체 프록시를 통해 요청하는 경우 프록시 base URL을 전달하고 API 키는 `null` 또는 빈 문자열로 생략할 수 있습니다. API 키가 비어 있거나 없으면 SDK는 `X-API-KEY` 헤더를 보내지 않습니다. 기본 Typecast 호스트로 요청할 때는 API 키가 계속 필요합니다.
</Info>

```java API 키 없는 프록시 theme={null}
TypecastClient client = new TypecastClient(null, "https://your-proxy.example.com");
```

### 환경 파일

프로젝트 루트에 `.env` 파일을 만드세요:

```bash theme={null}
TYPECAST_API_KEY=your-api-key-here
```

## 고급 사용법

### 감정 제어 (ssfm-v30)

ssfm-v30은 두 가지 감정 제어 모드를 제공합니다: **프리셋** 및 **스마트**.

<Tabs>
  <Tab title="스마트 모드">
    AI가 문맥에서 감정을 추론하도록 합니다:

    ```java theme={null}
    TTSRequest request = TTSRequest.builder()
            .voiceId("tc_672c5f5ce59fac2a48faeaee")
            .text("모든 것이 잘 될 거예요.")
            .model(TTSModel.SSFM_V30)
            .prompt(SmartPrompt.builder()
                    .previousText("방금 최고의 소식을 들었어요!")  // 선택적 문맥
                    .nextText("축하할 수 있어서 너무 기다려져요!")     // 선택적 문맥
                    .build())
            .build();

    TTSResponse response = client.textToSpeech(request);
    ```
  </Tab>

  <Tab title="프리셋 모드">
    프리셋 값으로 감정을 명시적으로 설정합니다:

    ```java theme={null}
    TTSRequest request = TTSRequest.builder()
            .voiceId("tc_672c5f5ce59fac2a48faeaee")
            .text("이 기능들을 보여드리게 되어 정말 기대됩니다!")
            .model(TTSModel.SSFM_V30)
            .prompt(PresetPrompt.builder()
                    .emotionPreset(EmotionPreset.HAPPY)  // normal, happy, sad, angry, whisper, toneup, tonedown
                    .emotionIntensity(1.5)               // 범위: 0.0 ~ 2.0
                    .build())
            .build();

    TTSResponse response = client.textToSpeech(request);
    ```
  </Tab>
</Tabs>

### 오디오 사용자 정의

라우드니스, 피치, 템포 및 출력 형식을 제어합니다:

```java theme={null}
TTSRequest request = TTSRequest.builder()
        .voiceId("tc_672c5f5ce59fac2a48faeaee")
        .text("사용자 정의 오디오 출력!")
        .model(TTSModel.SSFM_V30)
        .output(Output.builder()
                .targetLufs(-14.0)                 // 범위: -70 ~ 0 (LUFS)
                .audioPitch(2)                  // 범위: -12 to +12 반음
                .audioTempo(1.2)                // 범위: 0.5x to 2.0x
                .audioFormat(AudioFormat.MP3)   // 옵션: WAV, MP3
                .build())
        .seed(42)  // 0 이상의 정수 시드 (재현 가능한 결과)
        .build();

TTSResponse response = client.textToSpeech(request);

try (FileOutputStream fos = new FileOutputStream("output." + response.getFormat())) {
    fos.write(response.getAudioData());
}
System.out.println("Duration: " + response.getDuration() + "s, Format: " + response.getFormat());
```

### 파일로 바로 생성하기

`generateToFile`은 음성 합성과 파일 저장을 한 번에 처리합니다. `model`은 기본값으로 `ssfm-v30`을 사용하고, `.mp3` 또는 `.wav` 확장자로 출력 형식을 결정합니다.

```java theme={null}
client.generateToFile("output.mp3", GenerateToFileRequest.builder()
    .text("안녕하세요, 타입캐스트입니다.")
    .voiceId("tc_672c5f5ce59fac2a48faeaee") // voice_id는 https://typecast.ai/developers/api/voices 에서 확인하세요.
    .build());
```

### 텍스트만으로 쉼 표현

한 voice로 읽는 문장 안에 쉼만 넣고 싶다면 텍스트에 pause markup을 직접 작성합니다. `<|5s|>`, `<|1s|>`, `<|0.3s|>`, `<|0.34413s|>`처럼 쓰며 값은 초 단위이고 반드시 `s`로 끝납니다. 별도 pause 함수를 호출하지 않아도 텍스트만 보고 쉼 위치를 확인할 수 있습니다.

```java theme={null}
TTSResponse audio = client.composeSpeech()
    .defaults(new ComposerSettings().voiceId("tc_672c5f5ce59fac2a48faeaee").model(TTSModel.SSFM_V30))
    .say("안녕하세요<|5s|>반갑습니다<|1s|>오늘<|2s|>날씨는 어떤 것 같으세요?")
    .generate();
```

### 다중 화자 합성

한 파일 안에서 서로 다른 voice나 구간별 pitch, tempo, prompt, seed 같은 옵션을 조합해야 할 때 사용합니다. composer는 각 구간을 WAV로 생성하고 앞뒤 무음 PCM 샘플을 trim한 뒤 합성합니다. MP3가 필요하면 먼저 WAV를 생성한 다음 앱 또는 서버 파이프라인에서 변환하세요.

```java theme={null}
TypecastClient client = new TypecastClient("YOUR_API_KEY");

TTSResponse audio = client.composeSpeech()
    .defaults(new ComposerSettings().setVoiceId("tc_672c5f5ce59fac2a48faeaee").setModel(TTSModel.SSFM_V30))
    .say("Hello there")
    .pause(5)
    .say("Nice to meet you", new ComposerSettings()
        .setVoiceId("tc_60e5426de8b95f1d3000d7b5")
        .setOutput(Output.builder().volume(null).audioPitch(2).build()))
    .say("Today")
    .pause(2)
    .say("How does the weather feel?")
    .generate();

Files.write(Path.of("conversation.wav"), audio.getAudioData());
```

### 음성 탐색 (V2 API)

향상된 메타데이터로 사용 가능한 음성을 나열하고 필터링합니다:

```java theme={null}
// 모든 음성 가져오기
List<VoiceV2Response> voices = client.getVoicesV2();

// 기준으로 필터링
VoicesV2Filter filter = VoicesV2Filter.builder()
        .model(TTSModel.SSFM_V30)
        .gender(GenderEnum.FEMALE)
        .age(AgeEnum.YOUNG_ADULT)
        .build();

List<VoiceV2Response> filtered = client.getVoicesV2(filter);

// 음성 정보 표시
for (VoiceV2Response voice : voices) {
    System.out.println("ID: " + voice.getVoiceId() + ", Name: " + voice.getVoiceName());
    System.out.println("Gender: " + voice.getGender() + ", Age: " + voice.getAge());

    for (ModelInfo model : voice.getModels()) {
        System.out.println("Model: " + model.getVersion() + ", Emotions: " + model.getEmotions());
    }

    if (voice.getUseCases() != null) {
        System.out.println("Use cases: " + String.join(", ", voice.getUseCases()));
    }
}
```

### 스트리밍

저지연 재생을 위한 실시간 오디오 청크 스트리밍:

```java theme={null}
import javax.sound.sampled.*;

// 오디오 재생 설정: 32000 Hz, 16비트, 모노, 리틀엔디안
AudioFormat format = new AudioFormat(32000, 16, 1, true, false);
SourceDataLine line = AudioSystem.getSourceDataLine(format);
line.open(format, 8192);
line.start();

try (InputStream stream = client.textToSpeechStream(request)) {
    byte[] buf = new byte[4096];
    boolean first = true;
    int bytesRead;

    while ((bytesRead = stream.read(buf)) != -1) {
        int offset = 0;
        if (first) {
            offset = 44;           // 44바이트 WAV 헤더 건너뛰기
            bytesRead -= 44;
            first = false;
        }
        line.write(buf, offset, bytesRead);
    }
}
line.drain();
line.close();
client.close();
```

<Note>
  **WAV 스트리밍 형식:** 32000 Hz, 16비트, 모노 PCM. 첫 번째 청크에 44바이트 WAV 헤더(size = `0xFFFFFFFF`)가 포함되며, 이후 청크는 원시 PCM 데이터만 포함합니다. MP3 형식: 320 kbps, 44100 Hz, 각 청크는 독립적으로 디코딩 가능합니다. `java.io.OutputStream`과의 이름 충돌을 피하려면 `com.neosapience.models.OutputStream`으로 정규화된 이름을 사용하세요.
</Note>

## 타임스탬프 TTS

`textToSpeechWithTimestamps()`는 `POST /v1/text-to-speech/with-timestamps`를 래핑하며, 오디오와 함께 단어·문자 단위 정렬 데이터를 반환합니다. 가라오케 하이라이트, 자막 생성, 립싱크 애플리케이션에 활용할 수 있습니다.

### 기본 사용법

```java theme={null}
import com.neosapience.TypecastClient;
import com.neosapience.models.TTSRequestWithTimestamps;
import com.neosapience.models.TTSWithTimestampsResponse;
import java.nio.file.Files;
import java.nio.file.Paths;

TypecastClient client = new TypecastClient("YOUR_API_KEY");

TTSWithTimestampsResponse result = client.textToSpeechWithTimestamps(
    TTSRequestWithTimestamps.builder()
        .voiceId("tc_60e5426de8b95f1d3000d7b5")
        .text("Hello. How are you?")
        .model("ssfm-v30")
        .build()
);

Files.write(Paths.get("output.wav"), result.audioBytes());
System.out.printf("재생 시간: %.3f초%n", result.getAudioDuration());

for (var word : result.getWords()) {
    System.out.printf("  [%.3fs – %.3fs] %s%n",
        word.getStartTime(), word.getEndTime(), word.getText());
}
```

### 정밀도(Granularity) 설정

`granularity("word")`(기본값) 또는 `granularity("char")`을 설정해 정렬 단위를 제어합니다.

```java theme={null}
// 문자 단위 정렬 — 일본어·중국어에 필수
TTSWithTimestampsResponse result = client.textToSpeechWithTimestamps(
    TTSRequestWithTimestamps.builder()
        .voiceId("tc_60e5426de8b95f1d3000d7b5")
        .text("Hello. How are you?")
        .model("ssfm-v30")
        .granularity("char")
        .build()
);
```

### 자막 내보내기

```java theme={null}
String srt = result.toSrt();
Files.writeString(Paths.get("output.srt"), srt);

String vtt = result.toVtt();
Files.writeString(Paths.get("output.vtt"), vtt);
```

<Note>
  **일본어·중국어:** 공백 구분자가 없는 언어(jpn, zho)는 단어 단위 세그먼트가 의미를 갖지 않습니다. 해당 언어에는 `granularity("char")`를 사용해 문자 단위 정렬 데이터를 얻으세요.
</Note>

## 지원 언어

SDK는 자동 언어 감지와 함께 37개 언어를 지원합니다:

| 코드    | 언어    | 코드    | 언어     | 코드    | 언어     |
| ----- | ----- | ----- | ------ | ----- | ------ |
| `ENG` | 영어    | `JPN` | 일본어    | `UKR` | 우크라이나어 |
| `KOR` | 한국어   | `ELL` | 그리스어   | `IND` | 인도네시아어 |
| `SPA` | 스페인어  | `TAM` | 타밀어    | `DAN` | 덴마크어   |
| `DEU` | 독일어   | `TGL` | 타갈로그어  | `SWE` | 스웨덴어   |
| `FRA` | 프랑스어  | `FIN` | 핀란드어   | `MSA` | 말레이어   |
| `ITA` | 이탈리아어 | `ZHO` | 중국어    | `CES` | 체코어    |
| `POL` | 폴란드어  | `SLK` | 슬로바키아어 | `POR` | 포르투갈어  |
| `NLD` | 네덜란드어 | `ARA` | 아랍어    | `BUL` | 불가리아어  |
| `RUS` | 러시아어  | `HRV` | 크로아티아어 | `RON` | 루마니아어  |
| `BEN` | 벵골어   | `HIN` | 힌디어    | `HUN` | 헝가리어   |
| `NAN` | 민난어   | `NOR` | 노르웨이어  | `PAN` | 펀자브어   |
| `THA` | 태국어   | `TUR` | 터키어    | `VIE` | 베트남어   |
| `YUE` | 광둥어   |       |        |       |        |

<Info>
  지정하지 않으면 입력 텍스트에서 언어가 자동으로 감지됩니다.
</Info>

## 오류 처리

SDK는 API 오류 처리를 위한 특정 예외 클래스를 제공합니다:

```java theme={null}
import com.neosapience.TypecastClient;
import com.neosapience.exceptions.*;

try {
    TTSResponse response = client.textToSpeech(request);
} catch (UnauthorizedException e) {
    // 401: 잘못된 API 키
    System.err.println("Invalid API key: " + e.getMessage());
} catch (PaymentRequiredException e) {
    // 402: 크레딧 부족
    System.err.println("Insufficient credits: " + e.getMessage());
} catch (ForbiddenException e) {
    // 403: 접근 거부
    System.err.println("Access denied: " + e.getMessage());
} catch (NotFoundException e) {
    // 404: 리소스를 찾을 수 없음
    System.err.println("Voice not found: " + e.getMessage());
} catch (UnprocessableEntityException e) {
    // 422: 유효성 검사 오류
    System.err.println("Validation error: " + e.getMessage());
} catch (RateLimitException e) {
    // 429: 요청 한도 초과
    System.err.println("Rate limit exceeded - please try again later");
} catch (InternalServerException e) {
    // 500: 서버 오류
    System.err.println("Server error: " + e.getMessage());
} catch (TypecastException e) {
    // 일반 오류
    System.err.println("API error (" + e.getStatusCode() + "): " + e.getMessage());
}
```

### 예외 계층 구조

| 예외                             | 상태 코드 | 설명              |
| ------------------------------ | ----- | --------------- |
| `BadRequestException`          | 400   | 잘못된 요청 매개변수     |
| `UnauthorizedException`        | 401   | 잘못되거나 누락된 API 키 |
| `PaymentRequiredException`     | 402   | 크레딧 부족          |
| `ForbiddenException`           | 403   | 접근 거부           |
| `NotFoundException`            | 404   | 리소스를 찾을 수 없음    |
| `UnprocessableEntityException` | 422   | 유효성 검사 오류       |
| `RateLimitException`           | 429   | 요청 한도 초과        |
| `InternalServerException`      | 500   | 서버 오류           |
| `TypecastException`            | \*    | 기본 예외 클래스       |