> For the complete documentation index, see [llms.txt](https://docs.nuclearplayer.com/nuclear/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nuclearplayer.com/nuclear/plugins/ytdlp.md).

# yt-dlp

## yt-dlp API for Plugins

The yt-dlp API gives plugins access to the [yt-dlp](https://github.com/yt-dlp/yt-dlp) command-line tool for searching YouTube and resolving direct audio stream URLs.

Unless you want your plugin to integrate with Youtube, you probably won't need this API at all.

{% hint style="warning" %}
yt-dlp is a system dependency. If it's not installed on the user's machine, this API won't be available. Always check `api.Ytdlp.available` before calling any methods.
{% endhint %}

***

## Availability

The yt-dlp host is only configured when Nuclear detects a working yt-dlp binary on the system. The `available` getter tells you whether you can use the API:

```typescript
import type { NuclearPluginAPI } from '@nuclearplayer/plugin-sdk';

export default {
  async onEnable(api: NuclearPluginAPI) {
    if (!api.Ytdlp.available) {
      api.Logger.warn('yt-dlp is not installed, skipping YouTube features');
      return;
    }

    // Safe to call search() and getStream() here
  },
};
```

If you call `search()` or `getStream()` without a configured host, they throw `Error('YtdlpAPI: No host configured')`.

***

## Usage

{% tabs %}
{% tab title="Searching" %}

```typescript
import type { NuclearPluginAPI } from '@nuclearplayer/plugin-sdk';

export default {
  async onEnable(api: NuclearPluginAPI) {
    if (!api.Ytdlp.available) return;

    const results = await api.Ytdlp.search('Radiohead Paranoid Android', 5);

    for (const result of results) {
      api.Logger.info(`${result.title} (${result.id})`);

      if (result.duration) {
        api.Logger.info(`Duration: ${result.duration}s`);
      }
    }
  },
};
```

{% endtab %}

{% tab title="Getting streams" %}

```typescript
import type { NuclearPluginAPI } from '@nuclearplayer/plugin-sdk';

export default {
  async onEnable(api: NuclearPluginAPI) {
    if (!api.Ytdlp.available) return;

    const results = await api.Ytdlp.search('Radiohead Paranoid Android', 1);
    if (results.length === 0) return;

    const stream = await api.Ytdlp.getStream(results[0].id);
    api.Logger.info(`Stream URL: ${stream.stream_url}`);
  },
};
```

{% endtab %}
{% endtabs %}

***

## Data types

### `YtdlpSearchResult`

Returned by `search()`. Represents a YouTube video matching the query.

| Field       | Type             | Description                               |
| ----------- | ---------------- | ----------------------------------------- |
| `id`        | `string`         | YouTube video ID                          |
| `title`     | `string`         | Video title                               |
| `duration`  | `number \| null` | Duration in seconds, or `null` if unknown |
| `thumbnail` | `string \| null` | Thumbnail URL, or `null` if unavailable   |

### `YtdlpStreamInfo`

Returned by `getStream()`. Contains the resolved audio stream URL.

| Field        | Type             | Description             |
| ------------ | ---------------- | ----------------------- |
| `stream_url` | `string`         | Direct audio stream URL |
| `duration`   | `number \| null` | Duration in seconds     |
| `title`      | `string \| null` | Video title             |

{% hint style="info" %}
These types mirror the Rust types in `packages/player/src-tauri/src/ytdlp.rs`.
{% endhint %}

***

## Reference

```typescript
// Availability
api.Ytdlp.available: boolean

// Search YouTube for videos
api.Ytdlp.search(query: string, maxResults?: number): Promise<YtdlpSearchResult[]>

// Resolve a video ID to a playable stream URL
api.Ytdlp.getStream(videoId: string): Promise<YtdlpStreamInfo>
```

***

## Stream expiry

Audio stream URLs from YouTube are ephemeral. They expire after a few hours. Don't store them for later use. Resolve a fresh URL each time you need to play a track.

{% hint style="info" %}
This API is primarily used by streaming providers. Most plugins won't need it.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nuclearplayer.com/nuclear/plugins/ytdlp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.