Metadata-Version: 2.4
Name: youtubetranscriptdevapi
Version: 0.1.0
Summary: Official Python SDK for YouTubeTranscript.dev — extract, transcribe, and translate YouTube video transcripts
Project-URL: Homepage, https://youtubetranscript.dev
Project-URL: Documentation, https://youtubetranscript.dev/api-docs
Project-URL: Repository, https://github.com/youtubetranscript/python-sdk
Project-URL: Issues, https://github.com/youtubetranscript/python-sdk/issues
Project-URL: Dashboard, https://youtubetranscript.dev/dashboard
Author-email: "YouTubeTranscript.dev" <support@youtubetranscript.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: asr,captions,speech-recognition,subtitles,transcript,video-to-text,youtube,youtube-transcript
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: httpx>=0.24.0
Provides-Extra: async
Requires-Dist: httpx[http2]>=0.24.0; extra == 'async'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# YouTubeTranscript Python SDK

Official Python client for the [YouTubeTranscript.dev](https://youtubetranscript.dev) API — extract, transcribe, and translate YouTube video transcripts.

## Installation

```bash
pip install youtubetranscript
```

## Quick Start

```python
from youtubetranscript import YouTubeTranscript

yt = YouTubeTranscript("your_api_key")

# Extract transcript
result = yt.transcribe("dQw4w9WgXcQ")

print(f"Segments: {len(result.segments)}")
print(f"Duration: {result.duration:.0f}s")
print(f"Words: {result.word_count}")

for seg in result.segments[:5]:
    print(f"[{seg.start_formatted}] {seg.text}")
```

Get your free API key at [youtubetranscript.dev/dashboard](https://youtubetranscript.dev/dashboard)

## Features

```python
# Translate to any language
result = yt.transcribe("dQw4w9WgXcQ", language="es")

# Choose caption source
result = yt.transcribe("dQw4w9WgXcQ", source="manual")

# Format options
result = yt.transcribe("dQw4w9WgXcQ", format={"timestamp": True, "words": True})

# Batch — up to 100 videos at once
batch = yt.batch(["video1", "video2", "video3"])
for t in batch.completed:
    print(f"{t.video_id}: {t.word_count} words")

# ASR audio transcription (for videos without captions)
job = yt.transcribe_asr("video_without_captions")
result = yt.wait_for_job(job.job_id)  # polls until complete
print(result.text)

# Export formats
print(result.to_srt())       # SRT subtitles
print(result.to_vtt())       # WebVTT subtitles
print(result.to_plain_text())       # Plain text
print(result.to_timestamped_text()) # Text with timestamps

# Search within transcript
matches = result.search("keyword")

# Account stats
stats = yt.stats()
print(f"Credits: {stats.credits_remaining}")

# History
history = yt.list_transcripts(search="python tutorial", limit=5)
```

## Async Client

```python
import asyncio
from youtubetranscript import AsyncYouTubeTranscript

async def main():
    async with AsyncYouTubeTranscript("your_api_key") as yt:
        # Single
        result = await yt.transcribe("dQw4w9WgXcQ")

        # Concurrent
        results = await asyncio.gather(
            yt.transcribe("video1"),
            yt.transcribe("video2"),
            yt.transcribe("video3"),
        )

asyncio.run(main())
```

## Error Handling

```python
from youtubetranscript import YouTubeTranscript
from youtubetranscript.exceptions import (
    NoCaptionsError,
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError,
)

yt = YouTubeTranscript("your_api_key")

try:
    result = yt.transcribe("some_video")
except NoCaptionsError:
    # No captions — try ASR
    job = yt.transcribe_asr("some_video")
    result = yt.wait_for_job(job.job_id)
except AuthenticationError:
    print("Check your API key")
except InsufficientCreditsError:
    print("Top up at youtubetranscript.dev/pricing")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
```

## API Reference

### `YouTubeTranscript(api_key, *, base_url, timeout, max_retries)`

| Method | Description |
|--------|-------------|
| `transcribe(video, *, language, source, format)` | Extract transcript |
| `transcribe_asr(video, *, language, webhook_url)` | ASR audio transcription |
| `get_job(job_id)` | Check ASR job status |
| `wait_for_job(job_id, *, poll_interval, timeout)` | Poll until ASR completes |
| `batch(video_ids, *, language)` | Batch extract (up to 100) |
| `get_batch(batch_id)` | Check batch status |
| `list_transcripts(*, search, language, status, limit, page)` | Browse history |
| `get_transcript(video_id, *, language, source)` | Get saved transcript |
| `stats()` | Account credits & usage |
| `delete_transcript(*, video_id, ids)` | Delete transcripts |

### `Transcript` object

| Property/Method | Description |
|--------|-------------|
| `segments` | List of `Segment` objects |
| `text` | Full transcript as string |
| `video_id` | YouTube video ID |
| `language` | Transcript language |
| `word_count` | Total word count |
| `duration` | Total duration in seconds |
| `to_srt()` | Export as SRT |
| `to_vtt()` | Export as WebVTT |
| `to_plain_text()` | Plain text export |
| `to_timestamped_text()` | Text with `[MM:SS]` timestamps |
| `search(query)` | Find segments by text |

### `Segment` object

| Property | Description |
|----------|-------------|
| `text` | Segment text |
| `start` | Start time (seconds) |
| `end` | End time (seconds) |
| `duration` | Duration (seconds) |
| `start_formatted` | `"MM:SS"` format |
| `start_hms` | `"HH:MM:SS"` format |

## Credit Costs

| Operation | Cost |
|-----------|------|
| Captions extraction | 1 credit |
| Translation | 1 credit per 2,500 chars |
| ASR audio transcription | 1 credit per 90 seconds |
| Re-fetch owned transcript | Free |

## License

MIT — see [LICENSE](LICENSE)

## Links

- [Website](https://youtubetranscript.dev)
- [API Docs](https://youtubetranscript.dev/api-docs)
- [Dashboard](https://youtubetranscript.dev/dashboard)
- [Pricing](https://youtubetranscript.dev/pricing)
