{"id":"cf9b7193-112b-485f-9de7-ebd70a66d777","shortId":"92UR39","kind":"skill","title":"blog-audio","tagline":"Generate audio narration of blog posts using Google Gemini TTS. Supports summary narration, full article read-aloud, and two-speaker podcast/dialogue mode with 30 voice options. Outputs MP3 with HTML5 audio embed code. Works standalone via /blog audio or internally from blog-writ","description":"# Blog Audio -- Gemini TTS Narration for Blog Posts\n\nGenerate professional audio narration of blog content using Google's Gemini TTS.\nThree modes: summary (200-300 word spoken overview), full article read-aloud,\nor two-speaker podcast dialogue. 30 voices, 80+ languages, HTML5 embed output.\n\n## Quick Reference\n\n| Command | What it does |\n|---------|-------------|\n| `/blog audio generate <file>` | Generate audio narration of a blog post |\n| `/blog audio voices` | Show available voices with characteristics |\n| `/blog audio setup` | Check/configure API key for Gemini TTS |\n\n## Prerequisites\n\n- Python 3.11+ (venv managed automatically by `run.py`)\n- `GOOGLE_AI_API_KEY` environment variable (same key used by blog-image)\n- FFmpeg (for WAV-to-MP3 conversion; falls back to WAV if missing)\n\n## Always Use run.py Wrapper\n\n```bash\n# CORRECT:\npython3 scripts/run.py generate_audio.py --text \"...\" --voice Charon --json\n\n# WRONG:\npython3 scripts/generate_audio.py --text \"...\"  # Fails without venv\n```\n\n## API Key Check (Gate Pattern)\n\nBefore generating audio, check for the API key:\n\n```bash\necho $GOOGLE_AI_API_KEY\n```\n\n- If set: proceed with generation\n- If not set: guide the user:\n  \"Audio generation requires a Google AI API key. Get one free at https://aistudio.google.com/apikey\n   Then set it: `export GOOGLE_AI_API_KEY=your-key`\n   This is the same key used by `/blog image` -- if image generation works, audio works too.\"\n- **When called internally** (from blog-write): return silently if key is missing.\n  Never block the writing workflow.\n\n## Setup\n\nFor `/blog audio setup`:\n\n1. Check if `GOOGLE_AI_API_KEY` is set in environment\n2. If blog-image is configured (check `.mcp.json`), the key is already available\n3. If not, guide user to https://aistudio.google.com/apikey\n4. Verify with a dry run: `python3 scripts/run.py generate_audio.py --text \"Test\" --dry-run --json`\n\n## Voice Selection\n\nFor `/blog audio voices`:\n\nLoad `references/voices.md` and present the voice catalog to the user.\n\nAsk the user which voice they prefer, or recommend based on content type:\n- **Article narration**: Charon (Informative) or Sadaltager (Knowledgeable)\n- **Tutorial/how-to**: Achird (Friendly) or Sulafat (Warm)\n- **News/analysis**: Rasalgethi (Informative) or Schedar (Even)\n- **Lifestyle/wellness**: Aoede (Breezy) or Vindemiatrix (Gentle)\n- **Dialogue host**: Puck (Upbeat) or Laomedeia (Upbeat)\n- **Dialogue expert**: Kore (Firm) or Charon (Informative)\n\n## Generation Workflow\n\nFor `/blog audio generate <file>`:\n\n### Step 1: Read the Blog Post\n\nRead the file and extract:\n- Title (from H1 or frontmatter)\n- Full content (markdown body)\n- Approximate word count\n\n### Step 2: Choose Mode\n\nAsk the user (or auto-select if they specified `--mode`):\n\n| Mode | When to use | Output |\n|------|-------------|--------|\n| **Summary** | Quick audio overview (1-2 min) | 200-300 word spoken summary |\n| **Full** | Complete read-aloud (5-15 min) | Full article as natural speech |\n| **Dialogue** | Podcast-style (3-8 min) | Two-person conversation about the article |\n\n### Step 3: Prepare Text\n\n**CRITICAL:** Claude prepares the text. The script does TTS only.\n\n**Summary mode:**\nWrite a 200-300 word spoken summary of the article. Rules:\n- Write as natural speech, not written text\n- Open with the article's key finding or answer\n- Cover 3-5 main takeaways\n- Close with actionable advice\n- No markdown, no \"In this article...\", no meta-commentary\n- Use conversational transitions (\"Here's what matters...\", \"The key finding is...\")\n\n**Full mode:**\nStrip the markdown content to clean spoken text:\n- Headings become natural transitions (\"Next, let's look at...\")\n- Links become plain text (remove URLs, keep anchor text)\n- Images and charts: omit or briefly describe (\"As the data shows...\")\n- Code blocks: describe verbally (\"The code uses a for-loop to...\")\n- Lists: convert to natural sentences\n- Remove frontmatter, schema markup, HTML tags\n- Add brief intro: \"This is [title], published on [date].\"\n\n**Dialogue mode:**\nWrite a 2-person conversation script about the article:\n- Speaker1 = Host (curious, asks good questions)\n- Speaker2 = Expert (knowledgeable, gives clear answers)\n- Format each line as: `[Speaker1] What's the key takeaway here?`\n- Cover the article's main points conversationally\n- 15-25 exchanges (produces ~3-8 minutes)\n- Natural, not stilted (\"That's a great point\" over \"Indeed, as the research indicates\")\n\n### Step 4: Select Voice\n\nIf the user chose a voice, use it. Otherwise, recommend based on mode:\n- Summary/Full: default to Charon (Informative)\n- Dialogue: default to Puck (Host) + Kore (Expert)\n\n### Step 5: Generate Audio\n\nWrite the prepared text to a temp file, then call:\n\n```bash\n# Single voice (summary or full mode)\npython3 scripts/run.py generate_audio.py \\\n  --text-file /tmp/blog_audio_prepared.txt \\\n  --voice Charon \\\n  --model flash \\\n  --output /path/to/audio/post-slug.mp3 \\\n  --json\n\n# Two voices (dialogue mode)\npython3 scripts/run.py generate_audio.py \\\n  --text-file /tmp/blog_audio_dialogue.txt \\\n  --voice Puck \\\n  --voice2 Kore \\\n  --model pro \\\n  --output /path/to/audio/post-slug-dialogue.mp3 \\\n  --json\n```\n\n**Model selection:**\n- `flash` (default): Fast, cheap. Good for summaries and standard narration.\n- `pro`: Higher quality. Use for dialogue mode or premium content.\n\n### Step 6: Deliver\n\nPresent the result to the user:\n1. **File path** -- where the audio was saved\n2. **Duration** -- human-readable (e.g., \"3:42\")\n3. **Embed code** -- ready-to-paste HTML5 audio tag\n4. **Cost** -- estimated API cost\n5. **Placement suggestion** -- where to insert the embed in the blog post\n\n## Embedding Guide\n\n### Standard HTML (Hugo, Jekyll, static sites)\n```html\n<audio controls preload=\"metadata\">\n  <source src=\"audio/post-slug.mp3\" type=\"audio/mpeg\">\n  Your browser does not support the audio element.\n</audio>\n```\n\n### MDX (Next.js, Gatsby)\n```jsx\n<audio controls preload=\"metadata\">\n  <source src=\"/audio/post-slug.mp3\" type=\"audio/mpeg\" />\n</audio>\n```\n\n### WordPress\n```\n[audio src=\"audio/post-slug.mp3\"]\n```\n\n### Placement\nInsert the audio player after the introduction (below the first H2) or at the\nvery top of the article with a label: \"Listen to this article\" or \"Audio version\".\n\n## Internal API (for blog-write)\n\nWhen invoked internally from blog-write:\n\n**Input:**\n- `text`: Prepared text (already cleaned by Claude)\n- `voice`: Voice name (default: Charon)\n- `voice2`: Second voice for dialogue (optional)\n- `model`: flash or pro\n- `output_path`: Where to save the file\n\n**Output:**\n```markdown\n### Audio Narration\n- **Path:** /path/to/audio/post-slug.mp3\n- **Duration:** 3:42\n- **Voice:** Charon\n- **Embed:** `<audio controls preload=\"metadata\"><source src=\"audio/post-slug.mp3\" type=\"audio/mpeg\"></audio>`\n```\n\n**Graceful fallback:** If `GOOGLE_AI_API_KEY` is not set, return immediately\nwith no error. The writing workflow continues without audio. Never block\nblog-write because audio generation is unavailable.\n\n## Error Handling\n\n| Error | Resolution |\n|-------|-----------|\n| GOOGLE_AI_API_KEY not set | Get key at https://aistudio.google.com/apikey |\n| FFmpeg not found | Install: `sudo apt install ffmpeg`. Falls back to WAV output. |\n| Rate limited | Wait and retry. Check limits at https://aistudio.google.com/rate-limit |\n| Text too long (>32k tokens) | Split into sections, generate separately |\n| Unknown voice name | Run `/blog audio voices` to see valid options |\n| API error | Check key validity, model availability (preview models) |\n| API key missing (internal call) | Return silently -- writing workflow continues |\n\n## Reference Documentation\n\nLoad on-demand -- do NOT load all at startup:\n- `references/voices.md` -- Full 30-voice catalog, recommendations by content type, dialogue pairings","tags":["blog","audio","claude","agricidaniel","agent-skills","ai-citations","ai-content","ai-marketing","ai-marketing-hub","blog-writing","claude-code","claude-code-skill"],"capabilities":["skill","source-agricidaniel","skill-blog-audio","topic-agent-skills","topic-ai-citations","topic-ai-content","topic-ai-marketing","topic-ai-marketing-hub","topic-blog","topic-blog-writing","topic-claude-code","topic-claude-code-skill","topic-claude-plugin","topic-claude-skill","topic-content-creation"],"categories":["claude-blog"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/AgriciDaniel/claude-blog/blog-audio","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add AgriciDaniel/claude-blog","source_repo":"https://github.com/AgriciDaniel/claude-blog","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 753 github stars · SKILL.md body (7,773 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:53:29.085Z","embedding":null,"createdAt":"2026-05-18T12:54:51.330Z","updatedAt":"2026-05-18T18:53:29.085Z","lastSeenAt":"2026-05-18T18:53:29.085Z","tsv":"'-15':462 '-2':449 '-25':669 '-300':74,452,502 '-5':528 '-8':474,673 '/apikey':227,311,1003 '/blog':42,102,112,120,246,275,330,398,1042 '/path/to/audio/post-slug-dialogue.mp3':771 '/path/to/audio/post-slug.mp3':751,950 '/rate-limit':1027 '/tmp/blog_audio_dialogue.txt':763 '/tmp/blog_audio_prepared.txt':745 '1':278,402,448,804 '15':668 '2':289,425,631,812 '200':73,451,501 '3':303,473,484,527,672,818,820,952 '3.11':131 '30':29,89,1082 '32k':1031 '4':312,690,830 '42':819,953 '5':461,719,835 '6':796 '80':91 'achird':364 'action':533 'add':618 'advic':534 'ai':138,199,218,233,282,961,993 'aistudio.google.com':226,310,1002,1026 'aistudio.google.com/apikey':225,309,1001 'aistudio.google.com/rate-limit':1025 'aloud':21,82,460 'alreadi':301,919 'alway':163 'anchor':582 'answer':525,649 'aoed':376 'api':124,139,183,194,200,219,234,283,833,903,962,994,1049,1058 'approxim':421 'apt':1009 'articl':18,79,356,465,482,508,520,540,637,663,891,898 'ask':343,428,641 'audio':3,5,36,43,51,60,103,106,113,121,190,213,252,276,331,399,446,721,809,828,862,869,875,900,947,977,984,1043 'audio/post-slug.mp3':871 'auto':433 'auto-select':432 'automat':134 'avail':116,302,1055 'back':158,1013 'base':352,703 'bash':167,196,732 'becom':567,576 'block':269,596,979 'blog':2,8,48,50,56,63,110,148,260,292,405,845,906,913,981 'blog-audio':1 'blog-imag':147,291 'blog-writ':47,259,905,912,980 'bodi':420 'breezi':377 'brief':619 'briefli':589 'browser':857 'call':256,731,1062 'catalog':339,1084 'characterist':119 'charon':174,358,393,709,747,927,955 'chart':586 'cheap':778 'check':185,191,279,296,1022,1051 'check/configure':123 'choos':426 'chose':696 'claud':488,922 'clean':563,920 'clear':648 'close':531 'code':38,595,600,822 'command':98 'commentari':544 'complet':457 'configur':295 'content':64,354,418,561,794,1087 'continu':975,1067 'convers':156,479,546,633,667 'convert':608 'correct':168 'cost':831,834 'count':423 'cover':526,661 'critic':487 'curious':640 'data':593 'date':626 'default':707,712,776,926 'deliv':797 'demand':1073 'describ':590,597 'dialogu':88,381,388,469,627,711,755,790,932,1089 'document':1069 'dri':316,324 'dry-run':323 'durat':813,951 'e.g':817 'echo':197 'element':863 'emb':37,94,821,842,956 'embed':847 'environ':141,288 'error':971,988,990,1050 'estim':832 'even':374 'exchang':670 'expert':389,645,717 'export':231 'extract':411 'fail':180 'fall':157,1012 'fallback':958 'fast':777 'ffmpeg':150,1004,1011 'file':409,729,744,762,805,944 'find':523,554 'firm':391 'first':882 'flash':749,775,935 'for-loop':603 'format':650 'found':1006 'free':223 'friend':365 'frontmatt':416,613 'full':17,78,417,456,464,556,737,1081 'gate':186 'gatsbi':866 'gemini':12,52,68,127 'generat':4,58,104,105,189,206,214,250,395,400,720,985,1036 'generate_audio.py':171,320,741,759 'gentl':380 'get':221,998 'give':647 'good':642,779 'googl':11,66,137,198,217,232,281,960,992 'grace':957 'great':681 'guid':210,306,848 'h1':414 'h2':883 'handl':989 'head':566 'higher':786 'host':382,639,715 'html':616,850,855 'html5':35,93,827 'hugo':851 'human':815 'human-read':814 'imag':149,247,249,293,584 'immedi':968 'inde':684 'indic':688 'inform':359,371,394,710 'input':915 'insert':840,873 'instal':1007,1010 'intern':45,257,902,910,1061 'intro':620 'introduct':879 'invok':909 'jekyl':852 'json':175,326,752,772 'jsx':867 'keep':581 'key':125,140,144,184,195,201,220,235,238,243,265,284,299,522,553,658,963,995,999,1052,1059 'knowledg':362,646 'kore':390,716,767 'label':894 'languag':92 'laomedeia':386 'let':571 'lifestyle/wellness':375 'limit':1018,1023 'line':652 'link':575 'list':607 'listen':895 'load':333,1070,1076 'long':1030 'look':573 'loop':605 'main':529,665 'manag':133 'markdown':419,536,560,946 'markup':615 'matter':551 'mcp.json':297 'mdx':864 'meta':543 'meta-commentari':542 'min':450,463,475 'minut':674 'miss':162,267,1060 'mode':27,71,427,438,439,498,557,628,705,738,756,791 'model':748,768,773,934,1054,1057 'mp3':33,155 'name':925,1040 'narrat':6,16,54,61,107,357,784,948 'natur':467,512,568,610,675 'never':268,978 'news/analysis':369 'next':570 'next.js':865 'omit':587 'on-demand':1071 'one':222 'open':517 'option':31,933,1048 'otherwis':701 'output':32,95,443,750,770,938,945,1016 'overview':77,447 'pair':1090 'past':826 'path':806,939,949 'pattern':187 'person':478,632 'placement':836,872 'plain':577 'player':876 'podcast':87,471 'podcast-styl':470 'podcast/dialogue':26 'point':666,682 'post':9,57,111,406,846 'prefer':349 'premium':793 'prepar':485,489,724,917 'prerequisit':129 'present':336,798 'preview':1056 'pro':769,785,937 'proceed':204 'produc':671 'profession':59 'publish':624 'puck':383,714,765 'python':130 'python3':169,177,318,739,757 'qualiti':787 'question':643 'quick':96,445 'rasalgethi':370 'rate':1017 'read':20,81,403,407,459 'read-aloud':19,80,458 'readabl':816 'readi':824 'ready-to-past':823 'recommend':351,702,1085 'refer':97,1068 'references/voices.md':334,1080 'remov':579,612 'requir':215 'research':687 'resolut':991 'result':800 'retri':1021 'return':262,967,1063 'rule':509 'run':317,325,1041 'run.py':136,165 'sadaltag':361 'save':811,942 'schedar':373 'schema':614 'script':493,634 'scripts/generate_audio.py':178 'scripts/run.py':170,319,740,758 'second':929 'section':1035 'see':1046 'select':328,434,691,774 'sentenc':611 'separ':1037 'set':203,209,229,286,966,997 'setup':122,273,277 'show':115,594 'silent':263,1064 'singl':733 'site':854 'skill' 'skill-blog-audio' 'source-agricidaniel' 'speaker':25,86 'speaker1':638,654 'speaker2':644 'specifi':437 'speech':468,513 'split':1033 'spoken':76,454,504,564 'src':870 'standalon':40 'standard':783,849 'startup':1079 'static':853 'step':401,424,483,689,718,795 'stilt':677 'strip':558 'style':472 'sudo':1008 'suggest':837 'sulafat':367 'summari':15,72,444,455,497,505,735,781 'summary/full':706 'support':14,860 'tag':617,829 'takeaway':530,659 'temp':728 'test':322 'text':172,179,321,486,491,516,565,578,583,725,743,761,916,918,1028 'text-fil':742,760 'three':70 'titl':412,623 'token':1032 'top':888 'topic-agent-skills' 'topic-ai-citations' 'topic-ai-content' 'topic-ai-marketing' 'topic-ai-marketing-hub' 'topic-blog' 'topic-blog-writing' 'topic-claude-code' 'topic-claude-code-skill' 'topic-claude-plugin' 'topic-claude-skill' 'topic-content-creation' 'transit':547,569 'tts':13,53,69,128,495 'tutorial/how-to':363 'two':24,85,477,753 'two-person':476 'two-speak':23,84 'type':355,1088 'unavail':987 'unknown':1038 'upbeat':384,387 'url':580 'use':10,65,145,164,244,442,545,601,699,788 'user':212,307,342,345,430,695,803 'valid':1047,1053 'variabl':142 'venv':132,182 'verbal':598 'verifi':313 'version':901 'via':41 'vindemiatrix':379 'voic':30,90,114,117,173,327,332,338,347,692,698,734,746,754,764,923,924,930,954,1039,1044,1083 'voice2':766,928 'wait':1019 'warm':368 'wav':153,160,1015 'wav-to-mp3':152 'without':181,976 'word':75,422,453,503 'wordpress':868 'work':39,251,253 'workflow':272,396,974,1066 'wrapper':166 'writ':49 'write':261,271,499,510,629,722,907,914,973,982,1065 'written':515 'wrong':176 'your-key':236","prices":[{"id":"de1d5bb9-eb7f-4a4b-b59c-1389c812cc2b","listingId":"cf9b7193-112b-485f-9de7-ebd70a66d777","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"AgriciDaniel","category":"claude-blog","install_from":"skills.sh"},"createdAt":"2026-05-18T12:54:51.330Z"}],"sources":[{"listingId":"cf9b7193-112b-485f-9de7-ebd70a66d777","source":"github","sourceId":"AgriciDaniel/claude-blog/blog-audio","sourceUrl":"https://github.com/AgriciDaniel/claude-blog/tree/main/skills/blog-audio","isPrimary":false,"firstSeenAt":"2026-05-18T12:54:51.330Z","lastSeenAt":"2026-05-18T18:53:29.085Z"}],"details":{"listingId":"cf9b7193-112b-485f-9de7-ebd70a66d777","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"AgriciDaniel","slug":"blog-audio","github":{"repo":"AgriciDaniel/claude-blog","stars":753,"topics":["agent-skills","ai","ai-citations","ai-content","ai-marketing","ai-marketing-hub","blog","blog-writing","claude-code","claude-code-skill","claude-plugin","claude-skill","content-creation","content-optimization","content-strategy","eeat","geo","multilingual","open-source","seo"],"license":"mit","html_url":"https://github.com/AgriciDaniel/claude-blog","pushed_at":"2026-05-15T04:45:18Z","description":"Claude Code blog skill suite: 30 sub-skills, 5 agents, 5-gate v1.9.0 Blog Delivery Contract, dual-optimized for Google rankings and AI citations. Active development at AI-Marketing-Hub/claude-blog (AI Marketing Hub Pro community); public releases ship here.","skill_md_sha":"a0a8470647644a6d490b72208b4e6b20d6755154","skill_md_path":"skills/blog-audio/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/AgriciDaniel/claude-blog/tree/main/skills/blog-audio"},"layout":"multi","source":"github","category":"claude-blog","frontmatter":{"name":"blog-audio","license":"MIT","description":"Generate audio narration of blog posts using Google Gemini TTS. Supports summary narration, full article read-aloud, and two-speaker podcast/dialogue mode with 30 voice options. Outputs MP3 with HTML5 audio embed code. Works standalone via /blog audio or internally from blog-write. Falls back gracefully when API key is not configured. Use when user says \"blog audio\", \"narrate blog\", \"audio version\", \"text to speech\", \"tts\", \"podcast mode\", \"read aloud\", \"audio narration\", \"voice\", \"narration\", \"generate audio\"."},"skills_sh_url":"https://skills.sh/AgriciDaniel/claude-blog/blog-audio"},"updatedAt":"2026-05-18T18:53:29.085Z"}}