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

# Xuất

> Render video karaoke trên cloud hoặc cục bộ

Xuất (exports) sẽ render một bản karaoke đã hoàn thiện thành một tệp video. Dùng `client.exports.create(...)` làm điểm vào chính. Chọn `target: "local"` khi bạn muốn SDK render trực tiếp trên máy hiện tại; nếu không thì xuất trên cloud là mặc định.

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

Chọn đích xuất với `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, ... }
```

Dùng cloud khi bạn muốn một quy trình xuất async được quản lý. Dùng local khi bạn muốn render trực tiếp trên máy của bên gọi.

### Các trường dùng chung

| Trường             | Kiểu                                  | Mô tả                                                                        |
| ------------------ | ------------------------------------- | ---------------------------------------------------------------------------- |
| `resolution`       | `"540p" \| "720p" \| "1080p" \| "4k"` | Độ phân giải đầu ra.                                                         |
| `quality`          | `"low" \| "average" \| "high"`        | Chất lượng mã hoá.                                                           |
| `fps`              | `30 \| 60`                            | Số khung hình mỗi giây. Mặc định là `30`. Dùng `60` để chuyển động mượt hơn. |
| `playbackRate`     | `number`                              | Hệ số tốc độ (ví dụ `0.9`).                                                  |
| `toneFrequency`    | `number`                              | Dịch cao độ theo số bán âm (semitones).                                      |
| `transparent`      | `boolean`                             | Render với nền trong suốt.                                                   |
| `presetId`         | `string`                              | Áp dụng một preset trước khi render.                                         |
| `stemVolumes`      | `Record<string, number>`              | Ghi đè âm lượng theo từng stem, theo stem id.                                |
| `settingsOverride` | `object`                              | Patch cài đặt dự án chỉ cho lần xuất này.                                    |

Dùng `fps: 60` để chuyển động mượt hơn. Báo giá trên cloud áp dụng hệ số credit `1.5x` ở `60 fps`. Xuất cloud nền trong suốt 60 fps khả dụng khi độ dài và độ phân giải đã chọn nằm trong giới hạn cloud.

### Ví dụ với stem volumes

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

### Ví dụ với settings override

```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" },
    },
  },
});
```

Xem [Render settings reference](/en/render-settings-reference) để biết đầy đủ
cấu trúc `settingsOverride`.

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

Báo giá số credits cần cho một lần xuất trên cloud mà không khởi chạy xuất.

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

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

Xuất local chạy trên máy của bên gọi và không dùng credits xuất cloud,
vì vậy `quote(...)` chỉ dành cho xuất cloud.

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

Liệt kê các lần xuất của một dự án, có phân trang.

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

<ParamField path="page" type="number">
  Số trang. Mặc định là `1` trên server.
</ParamField>

<ParamField path="pageSize" type="number">
  Kích thước trang. Mặc định là `100`. Tối đa `100`.
</ParamField>

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

Lấy một export chỉ theo ID, không cần biết dự án cha.

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

## Xuất local

```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);
```

Dùng `onDependencyProgress` nếu bạn muốn cập nhật trong lúc bộ công cụ render local đang được cài đặt hoặc xác minh.

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

Trả về payload đã chuẩn bị cần thiết để render một export cục bộ. Dùng khi tích hợp với `@youka/remotion` hoặc một renderer local khác. Server trả về composition inputs, asset URLs, và render parameters mà không xếp hàng một lần render trên cloud.

```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(...)` không khởi chạy render trên cloud. Không có
  compute tính phí nào được tiêu thụ ở phía Youka.
</Note>

## Chờ một export

Xuất cloud là async. Dùng `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);
```

## Tải kết quả

Xuất cloud hoàn tất với một `url` đã ký. Dùng helper tích hợp sẵn để stream tệp xuống ổ đĩa. `output` có thể là một thư mục hoặc một đường dẫn tệp đầy đủ, và `filename` là tuỳ chọn:

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

## Tiếp theo

* [Tasks](/vi/sdk/tasks) — operation handles và polling nâng cao cho task
* [Presets](/vi/sdk/presets) — cấu hình render tái sử dụng
* [Project settings](/vi/sdk/project-settings) — patch cài đặt đang hoạt động của một dự án