# get_transcript

Fetch the transcript/captions for a YouTube video with intelligent language fallback.

## Parameters

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `video_url` | `string` | Yes | — | YouTube URL or video ID |
| `language` | `string` | No | `"en"` | Preferred language code (e.g. `en`, `es`, `fr`, `de`, `ja`, `ko`, `zh-Hans`, `pt`) |

### Supported URL Formats

All of the following are accepted as `video_url`:

```
https://www.youtube.com/watch?v=dQw4w9WgXcQ
https://youtu.be/dQw4w9WgXcQ
https://youtube.com/embed/dQw4w9WgXcQ
https://m.youtube.com/watch?v=dQw4w9WgXcQ
dQw4w9WgXcQ
```

The server extracts the 11-character video ID from any of these formats.

## Language Fallback Strategy

When the requested language is not available, the server applies a 4-step fallback:

1. **Exact match** — fetch the transcript in the requested language
2. **Auto-generated version** — try auto-generated captions for the requested language
3. **English variant** — fall back to any English transcript (`en-*`)
4. **First available** — return whatever transcript exists

This means a request for `language: "fr"` on a video with only English captions will still return a transcript rather than an error.

## Response Format

### Success Response

```json
{
  "video_id": "dQw4w9WgXcQ",
  "language": "English",
  "language_code": "en",
  "is_auto_generated": false,
  "segments": [
    {
      "start": 0.0,
      "duration": 4.5,
      "text": "We're no strangers to love"
    },
    {
      "start": 4.5,
      "duration": 3.2,
      "text": "You know the rules and so do I"
    }
  ],
  "full_text": "We're no strangers to love You know the rules and so do I ...",
  "total_segments": 42,
  "total_duration_seconds": 213.5
}
```

| Field | Type | Description |
|-------|------|-------------|
| `video_id` | `string` | The 11-character YouTube video ID |
| `language` | `string` | Human-readable language name |
| `language_code` | `string` | ISO language code of the returned transcript |
| `is_auto_generated` | `boolean` | `true` if the transcript was auto-generated by YouTube |
| `segments` | `array` | Timed transcript segments |
| `segments[].start` | `float` | Start time in seconds |
| `segments[].duration` | `float` | Segment duration in seconds |
| `segments[].text` | `string` | Transcript text for this segment |
| `full_text` | `string` | All segment text joined with spaces |
| `total_segments` | `integer` | Number of segments |
| `total_duration_seconds` | `float` | Sum of all segment durations |

## Error Handling

All errors return a structured error object:

```json
{
  "error": {
    "category": "client_error",
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}
```

### Error Types

| Code | Category | Description |
|------|----------|-------------|
| `INVALID_URL` | `client_error` | The `video_url` could not be parsed into a valid video ID |
| `TRANSCRIPTS_DISABLED` | `client_error` | The video has transcripts/captions disabled by the uploader |
| `NO_TRANSCRIPT_FOUND` | `client_error` | No transcript is available after all fallback attempts. Includes `available_languages` field listing what *is* available |
| `VIDEO_UNAVAILABLE` | `client_error` | The video does not exist, is private, or has been removed |
| `INTERNAL_ERROR` | `server_error` | An unexpected error occurred on the server |

### NO_TRANSCRIPT_FOUND Extended Response

When no transcript matches after fallback, the error includes available alternatives:

```json
{
  "error": {
    "category": "client_error",
    "code": "NO_TRANSCRIPT_FOUND",
    "message": "No transcript found for video: dQw4w9WgXcQ",
    "available_languages": ["en", "es", "fr"]
  }
}
```

## Examples

### Fetch English Transcript (default)

```
get_transcript(video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ")
```

### Fetch Spanish Transcript

```
get_transcript(
  video_url="https://youtu.be/dQw4w9WgXcQ",
  language="es"
)
```

### Using Just the Video ID

```
get_transcript(video_url="dQw4w9WgXcQ", language="ja")
```

## Source

Defined in [`src/__main__.py`](https://github.com/appmilla/youtube-transcript-mcp/blob/main/src/__main__.py) using `TranscriptClient` from [`src/services/transcript_client.py`](https://github.com/appmilla/youtube-transcript-mcp/blob/main/src/services/transcript_client.py).
