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

# 내보내기

> 클라우드 또는 로컬에서 가라오케 비디오를 렌더링

내보내기는 완성된 가라오케를 비디오 파일로 렌더링합니다. 메인 엔트리포인트로 `client.exports.create(...)`를 사용하세요. SDK가 현재 머신에서 직접 렌더링하게 하려면 `target: "local"`을 선택하고, 그렇지 않으면 기본값은 클라우드 내보내기입니다.

## `client.exports.create(projectId, input, options?)`

`target: "cloud" | "local"`로 내보내기 대상을 선택합니다.

```ts theme={null}
const cloud = await client.exports.create("prj_abc123", {
  resolution: "1080p",
  quality: "high",
});
// => ExportOperation

const local = await client.exports.create("prj_abc123", {
  target: "local",
  resolution: "1080p",
  quality: "high",
  outputPath: "./karaoke.mp4",
});
// => { outputPath, fileSize, duration, ... }
```

관리형 비동기 내보내기를 원하면 클라우드를 사용하세요. 호출자 머신에서 바로 렌더링하려면 로컬을 사용하세요.

### 공통 필드

| Field              | Type                                  | Description                                              |
| ------------------ | ------------------------------------- | -------------------------------------------------------- |
| `resolution`       | `"540p" \| "720p" \| "1080p" \| "4k"` | 출력 해상도.                                                  |
| `quality`          | `"low" \| "average" \| "high"`        | 인코딩 품질.                                                  |
| `fps`              | `30 \| 60`                            | 초당 프레임 수입니다. 기본값은 `30`입니다. 더 부드러운 움직임이 필요하면 `60`을 사용하세요. |
| `playbackRate`     | `number`                              | 속도 배수(예: `0.9`).                                         |
| `toneFrequency`    | `number`                              | 반음(semitones) 단위의 피치 시프트.                                |
| `transparent`      | `boolean`                             | 투명 배경으로 렌더링합니다.                                          |
| `presetId`         | `string`                              | 렌더링 전에 프리셋을 적용합니다.                                       |
| `stemVolumes`      | `Record<string, number>`              | stem id로 키잉된 stem별 볼륨 오버라이드.                             |
| `settingsOverride` | `object`                              | 이 내보내기에만 프로젝트 설정을 패치합니다.                                 |

`fps: 60`을 사용하면 더 부드러운 움직임을 얻을 수 있습니다. 클라우드 견적은 `60 fps`에서 `1.5x` 크레딧 배수를 적용합니다. 투명 60 fps 클라우드 내보내기는 선택한 길이와 해상도가 클라우드 제한에 맞을 때 사용할 수 있습니다.

### stem 볼륨 예시

```ts theme={null}
const result = await client.exports.create("prj_abc123", {
  resolution: "1080p",
  quality: "high",
  stemVolumes: {
    vocals: 0,
    instrumental: 1,
    backing: 0.5,
  },
});
```

### 설정 오버라이드 예시

```ts theme={null}
const result = await client.exports.create("prj_abc123", {
  resolution: "1080p",
  settingsOverride: {
    trim: { startSeconds: 5, endSeconds: 180 },
    style: {
      background: { type: "color", color: "#101010" },
    },
  },
});
```

전체 `settingsOverride` 형태는 [Render settings reference](/en/render-settings-reference)를 참고하세요.

## `client.exports.quote(projectId, input, options?)`

내보내기를 시작하지 않고 클라우드 내보내기에 필요한 크레딧을 견적합니다.

```ts theme={null}
const quote = await client.exports.quote("prj_abc123", {
  resolution: "1080p",
  quality: "high",
  transparent: false,
});

console.log(quote.creditsRequired, quote.sufficientBalance);
```

로컬 내보내기는 호출자 머신에서 실행되며 클라우드 내보내기 크레딧을 사용하지 않으므로 `quote(...)`는 클라우드 내보내기에서만 사용합니다.

## `client.exports.list(projectId, input?, options?)`

페이지네이션과 함께 프로젝트의 내보내기 목록을 조회합니다.

```ts theme={null}
const exports = await client.exports.list("prj_abc123", {
  page: 1,
  pageSize: 50,
});
```

<ParamField path="page" type="number">
  페이지 번호. 서버에서 기본값은 `1`입니다.
</ParamField>

<ParamField path="pageSize" type="number">
  페이지 크기. 기본값은 `100`입니다. 최대 `100`입니다.
</ParamField>

## `client.exports.get(exportId, options?)`

상위 프로젝트를 몰라도 ID만으로 내보내기를 가져옵니다.

```ts theme={null}
const exported = await client.exports.get("exp_xyz");
```

## 로컬 내보내기

```ts theme={null}
const result = await client.exports.create("prj_abc123", {
  target: "local",
  resolution: "1080p",
  quality: "high",
  outputPath: "./karaoke.mp4",
  onProgress(progress) {
    console.log(progress.stage, progress.percent);
  },
});

console.log(result.outputPath);
```

로컬 렌더 툴체인이 설치되거나 검증되는 동안 업데이트를 받고 싶다면 `onDependencyProgress`를 사용하세요.

## `client.exports.prepareLocal(projectId, body, options?)`

내보내기를 로컬에서 렌더링하는 데 필요한 준비된 페이로드를 반환합니다. `@youka/remotion` 또는 다른 로컬 렌더러와 통합할 때 사용하세요. 서버는 클라우드 렌더를 큐에 넣지 않고 컴포지션 입력, 에셋 URL, 렌더 파라미터를 반환합니다.

```ts theme={null}
const payload = await client.exports.prepareLocal("prj_abc123", {
  resolution: "1080p",
  quality: "high",
});

// Hand payload off to your local renderer
await renderLocally(payload);
```

<Note>
  `client.exports.prepareLocal(...)`는 클라우드 렌더를 시작하지 않습니다. Youka 측에서 과금되는
  compute가 소비되지 않습니다.
</Note>

## 내보내기 완료 대기

클라우드 내보내기는 비동기입니다. `client.exports.wait(...)`를 사용하세요:

```ts theme={null}
const operation = await client.exports.create("prj_abc123", {
  resolution: "1080p",
});

const finalized = await client.exports.wait(operation, {
  pollIntervalMs: 3_000,
});
console.log("Download from", finalized.url);
```

## 결과 다운로드

클라우드 내보내기는 서명된 `url`로 완료됩니다. 내장 헬퍼를 사용해 파일을 디스크로 스트리밍하세요. `output`은 디렉터리 또는 전체 파일 경로가 될 수 있으며, `filename`은 선택 사항입니다:

```ts theme={null}
await client.exports.download(finalized, {
  output: "./exports",
});
```

## 다음 단계

* [Tasks](/ko/sdk/tasks) — operation 핸들 및 고급 task 폴링
* [Presets](/ko/sdk/presets) — 재사용 가능한 렌더 구성
* [Project settings](/ko/sdk/project-settings) — 프로젝트의 활성 설정 패치하기