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

# Media

> Upload and manage reusable backgrounds, logos, and intro/outro videos

Media are reusable files — video backgrounds, static images, logos, and intro/outro clips — that you can reference from presets or project settings. Upload once and reuse across projects.

## Media types

| Type          | Description                      |
| ------------- | -------------------------------- |
| `video`       | Looping background video.        |
| `image`       | Static background image.         |
| `logo`        | Logo overlay.                    |
| `intro-video` | Plays before the karaoke starts. |
| `outro-video` | Plays after the karaoke ends.    |

## `client.media.list(options?)`

List every reusable media item owned by the authenticated account.

```ts theme={null}
const media = await client.media.list();
```

## `client.media.get(mediaId, options?)`

Fetch a single media item.

```ts theme={null}
const media = await client.media.get("bg_abc123");
```

## `client.media.create(body, options?)`

Create a new media item from a local path, bytes, or an existing uploaded `inputFileId`. For local paths and bytes, the SDK prepares the upload, sends the file bytes to the upload URL, and registers the uploaded file as reusable media.

```ts theme={null}
const media = await client.media.create({
  type: "video",
  source: {
    type: "path",
    path: "./background.mp4",
    contentType: "video/mp4",
  },
});
```

<ParamField path="type" type="'video' | 'image' | 'logo' | 'intro-video' | 'outro-video'" required>
  Which role this media item fills in a render.
</ParamField>

<ParamField path="source" type="object">
  The file source. Use `{ type: "path", path }` for local files, `{ type:
      "bytes", data, filename }` for `Blob`, `File`, `ArrayBuffer`, or typed array
  data, or `{ type: "inputFile", inputFileId }` when you already have an upload
  ID.
</ParamField>

<ParamField path="inputFileId" type="string">
  Advanced low-level option: pass the ID returned by
  `client.uploads.create(...)` instead of `source`.
</ParamField>

## `client.media.delete(mediaId, options?)`

Delete a media item.

```ts theme={null}
await client.media.delete("bg_abc123", {
  idempotencyKey: "delete-bg_abc123",
});
```

<Warning>
  Deleting media does not affect projects or exports that were previously
  rendered with it. Future renders that reference the deleted media will fall
  back to the default background.
</Warning>

## End-to-end example

```ts theme={null}
import { YoukaClient } from "@youka/sdk";

const client = new YoukaClient({ apiKey: process.env.YOUKA_API_KEY! });

async function uploadBackground(path: string, contentType: string) {
  return client.media.create({
    type: "video",
    source: {
      type: "path",
      path,
      contentType,
    },
  });
}

const media = await uploadBackground("./loop.mp4", "video/mp4");
console.log("Media ID:", media.id);
```

## Applying a background

Reference uploaded media from a preset or directly from project settings:

```ts theme={null}
const media = await uploadBackground("./loop.mp4", "video/mp4");

await client.projects.updateSettings("prj_abc123", {
  settings: {
    style: {
      background: {
        type: "video",
        url: media.url,
        objectFit: "cover",
      },
    },
  },
});
```

For the full set of fields accepted under `background`, convert the project settings schema to JSON:

```ts theme={null}
import { RestUpdateProjectSettingsRequestSchema } from "@youka/sdk";

const schema = RestUpdateProjectSettingsRequestSchema.toJSONSchema();
```

## What's next

* [Render settings reference](/en/render-settings-reference) — all shared field paths and enum values
* [Projects](/en/sdk/projects) — project creation and uploads
* [Presets](/en/sdk/presets) — bundle media with other render settings
* [Project settings](/en/sdk/project-settings) — apply backgrounds to a project