commit 9640b5e8bcdaa2c95bfa0d804ce2449eaf03b7ea Author: figmar Date: Sun Aug 9 08:19:24 2026 +0800 Publish hermes-skills-media via gitea-publish skill diff --git a/gif-search/SKILL.md b/gif-search/SKILL.md new file mode 100644 index 0000000..5416290 --- /dev/null +++ b/gif-search/SKILL.md @@ -0,0 +1,91 @@ +--- +name: gif-search +description: "Search/download GIFs from Tenor via curl + jq." +version: 1.1.0 +author: Hermes Agent +license: MIT +platforms: [linux, macos, windows] +prerequisites: + env_vars: [TENOR_API_KEY] + commands: [curl, jq] +metadata: + hermes: + tags: [GIF, Media, Search, Tenor, API] +--- + +# GIF Search (Tenor API) + +Search and download GIFs directly via the Tenor API using curl. No extra tools needed. + +## When to use + +Useful for finding reaction GIFs, creating visual content, and sending GIFs in chat. + +## Setup + +Set your Tenor API key in your environment (add to `${HERMES_HOME:-~/.hermes}/.env`): + +```bash +TENOR_API_KEY=your_key_here +``` + +Get a free API key at https://developers.google.com/tenor/guides/quickstart — the Google Cloud Console Tenor API key is free and has generous rate limits. + +## Prerequisites + +- `curl` and `jq` (both standard on macOS/Linux) +- `TENOR_API_KEY` environment variable + +## Search for GIFs + +```bash +# Search and get GIF URLs +curl -s "https://tenor.googleapis.com/v2/search?q=thumbs+up&limit=5&key=${TENOR_API_KEY}" | jq -r '.results[].media_formats.gif.url' + +# Get smaller/preview versions +curl -s "https://tenor.googleapis.com/v2/search?q=nice+work&limit=3&key=${TENOR_API_KEY}" | jq -r '.results[].media_formats.tinygif.url' +``` + +## Download a GIF + +```bash +# Search and download the top result +URL=$(curl -s "https://tenor.googleapis.com/v2/search?q=celebration&limit=1&key=${TENOR_API_KEY}" | jq -r '.results[0].media_formats.gif.url') +curl -sL "$URL" -o celebration.gif +``` + +## Get Full Metadata + +```bash +curl -s "https://tenor.googleapis.com/v2/search?q=cat&limit=3&key=${TENOR_API_KEY}" | jq '.results[] | {title: .title, url: .media_formats.gif.url, preview: .media_formats.tinygif.url, dimensions: .media_formats.gif.dims}' +``` + +## API Parameters + +| Parameter | Description | +|-----------|-------------| +| `q` | Search query (URL-encode spaces as `+`) | +| `limit` | Max results (1-50, default 20) | +| `key` | API key (from `$TENOR_API_KEY` env var) | +| `media_filter` | Filter formats: `gif`, `tinygif`, `mp4`, `tinymp4`, `webm` | +| `contentfilter` | Safety: `off`, `low`, `medium`, `high` | +| `locale` | Language: `en_US`, `es`, `fr`, etc. | + +## Available Media Formats + +Each result has multiple formats under `.media_formats`: + +| Format | Use case | +|--------|----------| +| `gif` | Full quality GIF | +| `tinygif` | Small preview GIF | +| `mp4` | Video version (smaller file size) | +| `tinymp4` | Small preview video | +| `webm` | WebM video | +| `nanogif` | Tiny thumbnail | + +## Notes + +- URL-encode the query: spaces as `+`, special chars as `%XX` +- For sending in chat, `tinygif` URLs are lighter weight +- GIF URLs can be used directly in markdown: `![alt](url)` diff --git a/heartmula/SKILL.md b/heartmula/SKILL.md new file mode 100644 index 0000000..e6adc4b --- /dev/null +++ b/heartmula/SKILL.md @@ -0,0 +1,171 @@ +--- +name: heartmula +description: "HeartMuLa: Suno-like song generation from lyrics + tags." +version: 1.0.0 +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [music, audio, generation, ai, heartmula, heartcodec, lyrics, songs] + related_skills: [audiocraft] +--- + +# HeartMuLa - Open-Source Music Generation + +## Overview +HeartMuLa is a family of open-source music foundation models (Apache-2.0) that generates music conditioned on lyrics and tags, with multilingual support. Generates full songs from lyrics + tags. Comparable to Suno for open-source. Includes: +- **HeartMuLa** - Music language model (3B/7B) for generation from lyrics + tags +- **HeartCodec** - 12.5Hz music codec for high-fidelity audio reconstruction +- **HeartTranscriptor** - Whisper-based lyrics transcription +- **HeartCLAP** - Audio-text alignment model + +## When to Use +- User wants to generate music/songs from text descriptions +- User wants an open-source Suno alternative +- User wants local/offline music generation +- User asks about HeartMuLa, heartlib, or AI music generation + +## Hardware Requirements +- **Minimum**: 8GB VRAM with `--lazy_load true` (loads/unloads models sequentially) +- **Recommended**: 16GB+ VRAM for comfortable single-GPU usage +- **Multi-GPU**: Use `--mula_device cuda:0 --codec_device cuda:1` to split across GPUs +- 3B model with lazy_load peaks at ~6.2GB VRAM + +## Installation Steps + +### 1. Clone Repository +```bash +cd ~/ # or desired directory +git clone https://github.com/HeartMuLa/heartlib.git +cd heartlib +``` + +### 2. Create Virtual Environment (Python 3.10 required) +```bash +uv venv --python 3.10 .venv +. .venv/bin/activate +uv pip install -e . +``` + +### 3. Fix Dependency Compatibility Issues + +**IMPORTANT**: As of Feb 2026, the pinned dependencies have conflicts with newer packages. Apply these fixes: + +```bash +# Upgrade datasets (old version incompatible with current pyarrow) +uv pip install --upgrade datasets + +# Upgrade transformers (needed for huggingface-hub 1.x compatibility) +uv pip install --upgrade transformers +``` + +### 4. Patch Source Code (Required for transformers 5.x) + +**Patch 1 - RoPE cache fix** in `src/heartlib/heartmula/modeling_heartmula.py`: + +In the `setup_caches` method of the `HeartMuLa` class, add RoPE reinitialization after the `reset_caches` try/except block and before the `with device:` block: + +```python +# Re-initialize RoPE caches that were skipped during meta-device loading +from torchtune.models.llama3_1._position_embeddings import Llama3ScaledRoPE +for module in self.modules(): + if isinstance(module, Llama3ScaledRoPE) and not module.is_cache_built: + module.rope_init() + module.to(device) +``` + +**Why**: `from_pretrained` creates model on meta device first; `Llama3ScaledRoPE.rope_init()` skips cache building on meta tensors, then never rebuilds after weights are loaded to real device. + +**Patch 2 - HeartCodec loading fix** in `src/heartlib/pipelines/music_generation.py`: + +Add `ignore_mismatched_sizes=True` to ALL `HeartCodec.from_pretrained()` calls (there are 2: the eager load in `__init__` and the lazy load in the `codec` property). + +**Why**: VQ codebook `initted` buffers have shape `[1]` in checkpoint vs `[]` in model. Same data, just scalar vs 0-d tensor. Safe to ignore. + +### 5. Download Model Checkpoints +```bash +cd heartlib # project root +hf download --local-dir './ckpt' 'HeartMuLa/HeartMuLaGen' +hf download --local-dir './ckpt/HeartMuLa-oss-3B' 'HeartMuLa/HeartMuLa-oss-3B-happy-new-year' +hf download --local-dir './ckpt/HeartCodec-oss' 'HeartMuLa/HeartCodec-oss-20260123' +``` + +All 3 can be downloaded in parallel. Total size is several GB. + +## GPU / CUDA + +HeartMuLa uses CUDA by default (`--mula_device cuda --codec_device cuda`). No extra setup needed if the user has an NVIDIA GPU with PyTorch CUDA support installed. + +- The installed `torch==2.4.1` includes CUDA 12.1 support out of the box +- `torchtune` may report version `0.4.0+cpu` — this is just package metadata, it still uses CUDA via PyTorch +- To verify GPU is being used, look for "CUDA memory" lines in the output (e.g. "CUDA memory before unloading: 6.20 GB") +- **No GPU?** You can run on CPU with `--mula_device cpu --codec_device cpu`, but expect generation to be **extremely slow** (potentially 30-60+ minutes for a single song vs ~4 minutes on GPU). CPU mode also requires significant RAM (~12GB+ free). If the user has no NVIDIA GPU, recommend using a cloud GPU service (Google Colab free tier with T4, Lambda Labs, etc.) or the online demo at https://heartmula.github.io/ instead. + +## Usage + +### Basic Generation +```bash +cd heartlib +. .venv/bin/activate +python ./examples/run_music_generation.py \ + --model_path=./ckpt \ + --version="3B" \ + --lyrics="./assets/lyrics.txt" \ + --tags="./assets/tags.txt" \ + --save_path="./assets/output.mp3" \ + --lazy_load true +``` + +### Input Formatting + +**Tags** (comma-separated, no spaces): +``` +piano,happy,wedding,synthesizer,romantic +``` +or +``` +rock,energetic,guitar,drums,male-vocal +``` + +**Lyrics** (use bracketed structural tags): +``` +[Intro] + +[Verse] +Your lyrics here... + +[Chorus] +Chorus lyrics... + +[Bridge] +Bridge lyrics... + +[Outro] +``` + +### Key Parameters +| Parameter | Default | Description | +|-----------|---------|-------------| +| `--max_audio_length_ms` | 240000 | Max length in ms (240s = 4 min) | +| `--topk` | 50 | Top-k sampling | +| `--temperature` | 1.0 | Sampling temperature | +| `--cfg_scale` | 1.5 | Classifier-free guidance scale | +| `--lazy_load` | false | Load/unload models on demand (saves VRAM) | +| `--mula_dtype` | bfloat16 | Dtype for HeartMuLa (bf16 recommended) | +| `--codec_dtype` | float32 | Dtype for HeartCodec (fp32 recommended for quality) | + +### Performance +- RTF (Real-Time Factor) ≈ 1.0 — a 4-minute song takes ~4 minutes to generate +- Output: MP3, 48kHz stereo, 128kbps + +## Pitfalls +1. **Do NOT use bf16 for HeartCodec** — degrades audio quality. Use fp32 (default). +2. **Tags may be ignored** — known issue (#90). Lyrics tend to dominate; experiment with tag ordering. +3. **Triton not available on macOS** — Linux/CUDA only for GPU acceleration. +4. **RTX 5080 incompatibility** reported in upstream issues. +5. The dependency pin conflicts require the manual upgrades and patches described above. + +## Links +- Repo: https://github.com/HeartMuLa/heartlib +- Models: https://huggingface.co/HeartMuLa +- Paper: https://arxiv.org/abs/2601.10547 +- License: Apache-2.0 diff --git a/songsee/SKILL.md b/songsee/SKILL.md new file mode 100644 index 0000000..a74c1ab --- /dev/null +++ b/songsee/SKILL.md @@ -0,0 +1,83 @@ +--- +name: songsee +description: "Audio spectrograms/features (mel, chroma, MFCC) via CLI." +version: 1.0.0 +author: community +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [Audio, Visualization, Spectrogram, Music, Analysis] + homepage: https://github.com/steipete/songsee +prerequisites: + commands: [songsee] +--- + +# songsee + +Generate spectrograms and multi-panel audio feature visualizations from audio files. + +## Prerequisites + +Requires [Go](https://go.dev/doc/install): +```bash +go install github.com/steipete/songsee/cmd/songsee@latest +``` + +Optional: `ffmpeg` for formats beyond WAV/MP3. + +## Quick Start + +```bash +# Basic spectrogram +songsee track.mp3 + +# Save to specific file +songsee track.mp3 -o spectrogram.png + +# Multi-panel visualization grid +songsee track.mp3 --viz spectrogram,mel,chroma,hpss,selfsim,loudness,tempogram,mfcc,flux + +# Time slice (start at 12.5s, 8s duration) +songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg + +# From stdin +cat track.mp3 | songsee - --format png -o out.png +``` + +## Visualization Types + +Use `--viz` with comma-separated values: + +| Type | Description | +|------|-------------| +| `spectrogram` | Standard frequency spectrogram | +| `mel` | Mel-scaled spectrogram | +| `chroma` | Pitch class distribution | +| `hpss` | Harmonic/percussive separation | +| `selfsim` | Self-similarity matrix | +| `loudness` | Loudness over time | +| `tempogram` | Tempo estimation | +| `mfcc` | Mel-frequency cepstral coefficients | +| `flux` | Spectral flux (onset detection) | + +Multiple `--viz` types render as a grid in a single image. + +## Common Flags + +| Flag | Description | +|------|-------------| +| `--viz` | Visualization types (comma-separated) | +| `--style` | Color palette: `classic`, `magma`, `inferno`, `viridis`, `gray` | +| `--width` / `--height` | Output image dimensions | +| `--window` / `--hop` | FFT window and hop size | +| `--min-freq` / `--max-freq` | Frequency range filter | +| `--start` / `--duration` | Time slice of the audio | +| `--format` | Output format: `jpg` or `png` | +| `-o` | Output file path | + +## Notes + +- WAV and MP3 are decoded natively; other formats require `ffmpeg` +- Output images can be inspected with `vision_analyze` for automated audio analysis +- Useful for comparing audio outputs, debugging synthesis, or documenting audio processing pipelines diff --git a/spotify/SKILL.md b/spotify/SKILL.md new file mode 100644 index 0000000..47fe0e2 --- /dev/null +++ b/spotify/SKILL.md @@ -0,0 +1,135 @@ +--- +name: spotify +description: "Spotify: play, search, queue, manage playlists and devices." +version: 1.0.0 +author: Hermes Agent +license: MIT +platforms: [linux, macos, windows] +prerequisites: + tools: [spotify_playback, spotify_devices, spotify_queue, spotify_search, spotify_playlists, spotify_albums, spotify_library] +metadata: + hermes: + tags: [spotify, music, playback, playlists, media] + related_skills: [gif-search] +--- + +# Spotify + +Control the user's Spotify account via the Hermes Spotify toolset (7 tools). Setup guide: https://hermes-agent.nousresearch.com/docs/user-guide/features/spotify + +## When to use this skill + +The user says something like "play X", "pause", "skip", "queue up X", "what's playing", "search for X", "add to my X playlist", "make a playlist", "save this to my library", etc. + +## The 7 tools + +- `spotify_playback` — play, pause, next, previous, seek, set_repeat, set_shuffle, set_volume, get_state, get_currently_playing, recently_played +- `spotify_devices` — list, transfer +- `spotify_queue` — get, add +- `spotify_search` — search the catalog +- `spotify_playlists` — list, get, create, add_items, remove_items, update_details +- `spotify_albums` — get, tracks +- `spotify_library` — list/save/remove with `kind: "tracks"|"albums"` + +Playback-mutating actions require Spotify Premium; search/library/playlist ops work on Free. + +## Canonical patterns (minimize tool calls) + +### "Play " +One search, then play by URI. Do NOT loop through search results describing them unless the user asked for options. + +``` +spotify_search({"query": "miles davis kind of blue", "types": ["album"], "limit": 1}) +→ got album URI spotify:album:1weenld61qoidwYuZ1GESA +spotify_playback({"action": "play", "context_uri": "spotify:album:1weenld61qoidwYuZ1GESA"}) +``` + +For "play some " (no specific song), prefer `types: ["artist"]` and play the artist context URI — Spotify handles smart shuffle. If the user says "the song" or "that track", search `types: ["track"]` and pass `uris: [track_uri]` to play. + +### "What's playing?" / "What am I listening to?" +Single call — don't chain get_state after get_currently_playing. + +``` +spotify_playback({"action": "get_currently_playing"}) +``` + +If it returns 204/empty (`is_playing: false`), tell the user nothing is playing. Don't retry. + +### "Pause" / "Skip" / "Volume 50" +Direct action, no preflight inspection needed. + +``` +spotify_playback({"action": "pause"}) +spotify_playback({"action": "next"}) +spotify_playback({"action": "set_volume", "volume_percent": 50}) +``` + +### "Add to my playlist" +1. `spotify_playlists list` to find the playlist ID by name +2. Get the track URI (from currently playing, or search) +3. `spotify_playlists add_items` with the playlist_id and URIs + +``` +spotify_playlists({"action": "list"}) +→ found "Late Night Jazz" = 37i9dQZF1DX4wta20PHgwo +spotify_playback({"action": "get_currently_playing"}) +→ current track uri = spotify:track:0DiWol3AO6WpXZgp0goxAV +spotify_playlists({"action": "add_items", + "playlist_id": "37i9dQZF1DX4wta20PHgwo", + "uris": ["spotify:track:0DiWol3AO6WpXZgp0goxAV"]}) +``` + +### "Create a playlist called X and add the last 3 songs I played" +``` +spotify_playback({"action": "recently_played", "limit": 3}) +spotify_playlists({"action": "create", "name": "Focus 2026"}) +→ got playlist_id back in response +spotify_playlists({"action": "add_items", "playlist_id": , "uris": [<3 uris>]}) +``` + +### "Save / unsave / is this saved?" +Use `spotify_library` with the right `kind`. + +``` +spotify_library({"kind": "tracks", "action": "save", "uris": ["spotify:track:..."]}) +spotify_library({"kind": "albums", "action": "list", "limit": 50}) +``` + +### "Transfer playback to my " +``` +spotify_devices({"action": "list"}) +→ pick the device_id by matching name/type +spotify_devices({"action": "transfer", "device_id": "", "play": true}) +``` + +## Critical failure modes + +**`403 Forbidden — No active device found`** on any playback action means Spotify isn't running anywhere. Tell the user: "Open Spotify on your phone/desktop/web player first, start any track for a second, then retry." Don't retry the tool call blindly — it will fail the same way. You can call `spotify_devices list` to confirm; an empty list means no active device. + +**`403 Forbidden — Premium required`** means the user is on Free and tried to mutate playback. Don't retry; tell them this action needs Premium. Reads still work (search, playlists, library, get_state). + +**`204 No Content` on `get_currently_playing`** is NOT an error — it means nothing is playing. The tool returns `is_playing: false`. Just report that to the user. + +**`429 Too Many Requests`** = rate limit. Wait and retry once. If it keeps happening, you're looping — stop. + +**`401 Unauthorized` after a retry** — refresh token revoked. Tell the user to run `hermes auth spotify` again. + +## URI and ID formats + +Spotify uses three interchangeable ID formats. The tools accept all three and normalize: + +- URI: `spotify:track:0DiWol3AO6WpXZgp0goxAV` (preferred) +- URL: `https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV` +- Bare ID: `0DiWol3AO6WpXZgp0goxAV` + +When in doubt, use full URIs. Search results return URIs in the `uri` field — pass those directly. + +Entity types: `track`, `album`, `artist`, `playlist`, `show`, `episode`. Use the right type for the action — `spotify_playback.play` with a `context_uri` expects album/playlist/artist; `uris` expects an array of track URIs. + +## What NOT to do + +- **Don't call `get_state` before every action.** Spotify accepts play/pause/skip without preflight. Only inspect state when the user asked "what's playing" or you need to reason about device/track. +- **Don't describe search results unless asked.** If the user said "play X", search, grab the top URI, play it. They'll hear it's wrong if it's wrong. +- **Don't retry on `403 Premium required` or `403 No active device`.** Those are permanent until user action. +- **Don't use `spotify_search` to find a playlist by name** — that searches the public Spotify catalog. User playlists come from `spotify_playlists list`. +- **Don't mix `kind: "tracks"` with album URIs** in `spotify_library` (or vice versa). The tool normalizes IDs but the API endpoint differs. diff --git a/youtube-content/SKILL.md b/youtube-content/SKILL.md new file mode 100644 index 0000000..3661aca --- /dev/null +++ b/youtube-content/SKILL.md @@ -0,0 +1,76 @@ +--- +name: youtube-content +description: "YouTube transcripts to summaries, threads, blogs." +platforms: [linux, macos, windows] +--- + +# YouTube Content Tool + +## When to use + +Use when the user shares a YouTube URL or video link, asks to summarize a video, requests a transcript, or wants to extract and reformat content from any YouTube video. Transforms transcripts into structured content (chapters, summaries, threads, blog posts). + +Extract transcripts from YouTube videos and convert them into useful formats. + +## Setup + +Use `uv` so the dependency is installed into the same Hermes-managed environment +that runs the helper script: + +```bash +uv pip install youtube-transcript-api +``` + +## Helper Script + +`SKILL_DIR` is the directory containing this SKILL.md file. The script accepts any standard YouTube URL format, short links (youtu.be), shorts, embeds, live links, or a raw 11-character video ID. + +```bash +# JSON output with metadata +uv run python3 SKILL_DIR/scripts/fetch_transcript.py "https://youtube.com/watch?v=VIDEO_ID" + +# Plain text (good for piping into further processing) +uv run python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --text-only + +# With timestamps +uv run python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --timestamps + +# Specific language with fallback chain +uv run python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --language tr,en +``` + +## Output Formats + +After fetching the transcript, format it based on what the user asks for: + +- **Chapters**: Group by topic shifts, output timestamped chapter list +- **Summary**: Concise 5-10 sentence overview of the entire video +- **Chapter summaries**: Chapters with a short paragraph summary for each +- **Thread**: Twitter/X thread format — numbered posts, each under 280 chars +- **Blog post**: Full article with title, sections, and key takeaways +- **Quotes**: Notable quotes with timestamps + +### Example — Chapters Output + +``` +00:00 Introduction — host opens with the problem statement +03:45 Background — prior work and why existing solutions fall short +12:20 Core method — walkthrough of the proposed approach +24:10 Results — benchmark comparisons and key takeaways +31:55 Q&A — audience questions on scalability and next steps +``` + +## Workflow + +1. **Fetch** the transcript using the helper script with `--text-only --timestamps` via `uv run python3`. +2. **Validate**: confirm the output is non-empty and in the expected language. If empty, retry without `--language` to get any available transcript. If still empty, tell the user the video likely has transcripts disabled. +3. **Chunk if needed**: if the transcript exceeds ~50K characters, split into overlapping chunks (~40K with 2K overlap) and summarize each chunk before merging. +4. **Transform** into the requested output format. If the user did not specify a format, default to a summary. +5. **Verify**: re-read the transformed output to check for coherence, correct timestamps, and completeness before presenting. + +## Error Handling + +- **Transcript disabled**: tell the user; suggest they check if subtitles are available on the video page. +- **Private/unavailable video**: relay the error and ask the user to verify the URL. +- **No matching language**: retry without `--language` to fetch any available transcript, then note the actual language to the user. +- **Dependency missing**: run `uv pip install youtube-transcript-api` and retry. diff --git a/youtube-content/references/output-formats.md b/youtube-content/references/output-formats.md new file mode 100644 index 0000000..c47d6aa --- /dev/null +++ b/youtube-content/references/output-formats.md @@ -0,0 +1,56 @@ +# Output Format Examples + +## Chapters + +``` +00:00 Introduction +02:15 Background and motivation +05:30 Main approach +12:45 Results and evaluation +18:20 Limitations and future work +21:00 Q&A +``` + +## Summary + +A 5-10 sentence overview covering the video's main points, key arguments, and conclusions. Written in third person, present tense. + +## Chapter Summaries + +``` +## 00:00 Introduction (2 min) +The speaker introduces the topic of X and explains why it matters for Y. + +## 02:15 Background (3 min) +A review of prior work in the field, covering approaches A, B, and C. +``` + +## Thread (Twitter/X) + +``` +1/ Just watched an incredible talk on [topic]. Here are the key takeaways: 🧵 + +2/ First insight: [point]. This matters because [reason]. + +3/ The surprising part: [unexpected finding]. Most people assume [common belief], but the data shows otherwise. + +4/ Practical takeaway: [actionable advice]. + +5/ Full video: [URL] +``` + +## Blog Post + +Full article with: +- Title +- Introduction paragraph +- H2 sections for each major topic +- Key quotes (with timestamps) +- Conclusion / takeaways + +## Quotes + +``` +"The most important thing is not the model size, but the data quality." — 05:32 +"We found that scaling past 70B parameters gave diminishing returns." — 12:18 +``` diff --git a/youtube-content/scripts/fetch_transcript.py b/youtube-content/scripts/fetch_transcript.py new file mode 100644 index 0000000..73c305c --- /dev/null +++ b/youtube-content/scripts/fetch_transcript.py @@ -0,0 +1,124 @@ +#!/usr/bin/env python3 +""" +Fetch a YouTube video transcript and output it as structured JSON. + +Usage: + uv run python3 fetch_transcript.py [--language en,tr] [--timestamps] + +Output (JSON): + { + "video_id": "...", + "language": "en", + "segments": [{"text": "...", "start": 0.0, "duration": 2.5}, ...], + "full_text": "complete transcript as plain text", + "timestamped_text": "00:00 first line\n00:05 second line\n..." + } + +Install dependency: uv pip install youtube-transcript-api +""" + +import argparse +import json +import re +import sys + + +def extract_video_id(url_or_id: str) -> str: + """Extract the 11-character video ID from various YouTube URL formats.""" + url_or_id = url_or_id.strip() + patterns = [ + r'(?:v=|youtu\.be/|shorts/|embed/|live/)([a-zA-Z0-9_-]{11})', + r'^([a-zA-Z0-9_-]{11})$', + ] + for pattern in patterns: + match = re.search(pattern, url_or_id) + if match: + return match.group(1) + return url_or_id + + +def format_timestamp(seconds: float) -> str: + """Convert seconds to HH:MM:SS or MM:SS format.""" + total = int(seconds) + h, remainder = divmod(total, 3600) + m, s = divmod(remainder, 60) + if h > 0: + return f"{h}:{m:02d}:{s:02d}" + return f"{m}:{s:02d}" + + +def fetch_transcript(video_id: str, languages: list = None): + """Fetch transcript segments from YouTube. + + Returns a list of dicts with 'text', 'start', and 'duration' keys. + Compatible with youtube-transcript-api v1.x. + """ + try: + from youtube_transcript_api import YouTubeTranscriptApi + except ImportError: + print("Error: youtube-transcript-api not installed. Run: uv pip install youtube-transcript-api", + file=sys.stderr) + sys.exit(1) + + api = YouTubeTranscriptApi() + if languages: + result = api.fetch(video_id, languages=languages) + else: + result = api.fetch(video_id) + + # v1.x returns FetchedTranscriptSnippet objects; normalize to dicts + return [ + {"text": seg.text, "start": seg.start, "duration": seg.duration} + for seg in result + ] + + +def main(): + parser = argparse.ArgumentParser(description="Fetch YouTube transcript as JSON") + parser.add_argument("url", help="YouTube URL or video ID") + parser.add_argument("--language", "-l", default=None, + help="Comma-separated language codes (e.g. en,tr). Default: auto") + parser.add_argument("--timestamps", "-t", action="store_true", + help="Include timestamped text in output") + parser.add_argument("--text-only", action="store_true", + help="Output plain text instead of JSON") + args = parser.parse_args() + + video_id = extract_video_id(args.url) + languages = [l.strip() for l in args.language.split(",")] if args.language else None + + try: + segments = fetch_transcript(video_id, languages) + except Exception as e: + error_msg = str(e) + if "disabled" in error_msg.lower(): + print(json.dumps({"error": "Transcripts are disabled for this video."})) + elif "no transcript" in error_msg.lower(): + print(json.dumps({"error": "No transcript found. Try specifying a language with --language."})) + else: + print(json.dumps({"error": error_msg})) + sys.exit(1) + + full_text = " ".join(seg["text"] for seg in segments) + timestamped = "\n".join( + f"{format_timestamp(seg['start'])} {seg['text']}" for seg in segments + ) + + if args.text_only: + print(timestamped if args.timestamps else full_text) + return + + result = { + "video_id": video_id, + "segment_count": len(segments), + "duration": format_timestamp(segments[-1]["start"] + segments[-1]["duration"]) if segments else "0:00", + "full_text": full_text, + } + if args.timestamps: + result["timestamped_text"] = timestamped + + print(json.dumps(result, ensure_ascii=False, indent=2)) + + +if __name__ == "__main__": + main()