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

# YouTube Utils

> Extract YouTube video IDs and build embed, watch, and thumbnail URLs from any YouTube link.

A tiny, dependency-free helper for working with YouTube links. It parses the video ID out of standard, short, embed, and Shorts URLs, then lets you generate clean embed, watch, and thumbnail URLs. Every function accepts either a full URL or a bare video ID and returns `null` when the input can't be resolved.

## Installation

Add the package to your project with Bun.

```bash theme={null}
bun add @ooneex/youtube-utils
```

## Usage

Import the function you need and pass it a URL or an existing video ID.

Extract the video ID from any supported YouTube URL:

```typescript theme={null}
import { getId } from "@ooneex/youtube-utils";

getId("https://www.youtube.com/watch?v=dQw4w9WgXcQ"); // "dQw4w9WgXcQ"
getId("https://youtu.be/dQw4w9WgXcQ"); // "dQw4w9WgXcQ"
getId("https://www.youtube.com/shorts/dQw4w9WgXcQ"); // "dQw4w9WgXcQ"
getId("not a youtube link"); // null
```

Build an embed URL for an iframe player. You can pass a full URL or just the ID:

```typescript theme={null}
import { getEmbedUrl } from "@ooneex/youtube-utils";

getEmbedUrl("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
// "https://www.youtube.com/embed/dQw4w9WgXcQ"

getEmbedUrl("dQw4w9WgXcQ");
// "https://www.youtube.com/embed/dQw4w9WgXcQ"
```

Generate a canonical watch URL:

```typescript theme={null}
import { getWatchUrl } from "@ooneex/youtube-utils";

getWatchUrl("https://youtu.be/dQw4w9WgXcQ");
// "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

Get a thumbnail image URL for a video:

```typescript theme={null}
import { getThumbnailUrl } from "@ooneex/youtube-utils";

getThumbnailUrl("dQw4w9WgXcQ");
// "https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg"
```

Each builder returns `null` when the input is neither a recognizable YouTube URL nor a valid-looking video ID, so you can guard before rendering:

```typescript theme={null}
import { getEmbedUrl } from "@ooneex/youtube-utils";

const embedUrl = getEmbedUrl(userInput);

if (embedUrl) {
  // safe to render the iframe
}
```

## When to use it

* Resolving a YouTube video ID from mixed link formats (`watch`, `youtu.be`, `embed`, `/v/`, Shorts).
* Rendering responsive `iframe` embeds from user-submitted YouTube links.
* Normalizing arbitrary YouTube URLs into a canonical `watch?v=` form.
* Displaying video thumbnails without calling the YouTube Data API.
* Validating that a string is a usable YouTube URL or ID before storing or rendering it.