{"id":"f88148c5-a115-47d1-b17d-0847d72ffdab","entityType":"agent","slug":"clawhub-spotify-save-to-spotify","name":"Save To Spotify","canonicalUrl":"https://www.xpersona.co/agent/clawhub-spotify-save-to-spotify","canonicalPath":"/agent/clawhub-spotify-save-to-spotify","generatedAt":"2026-10-10T14:44:23.785Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T11:58:02.991Z","emptyReason":null},"description":"Create polished audio content and save to Spotify. Produces episodes with TTS narration, a rich timeline (chapters plus in-player images, external links, and... Skill: Save To Spotify Owner: spotify Summary: Create polished audio content and save to Spotify. Produces episodes with TTS narration, a rich timeline (chapters plus in-player images, external links, and... Tags: latest:0.2.0 Version history: v0.2.0 | 2026-07-20T09:12:21.820Z | auto save-to-spotify v0.2.0 - Added comprehensive onboarding documentation and flow for first-time users ($1), enabling guided setup if the","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.4K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s178q1njn7prgvajksxt46zez58649bp:save-to-spotify","sourceUrl":"https://clawhub.ai/spotify/save-to-spotify","homepage":"https://clawhub.ai/spotify/skills/save-to-spotify","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/spotify/save-to-spotify","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/spotify/skills/save-to-spotify","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Create polished audio content and save to Spotify. Produces episodes with TTS narration, a rich timeline (chapters plus in-player images, external links, and..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:58:02.991Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:58:02.991Z","emptyReason":null},"stars":null,"forks":null,"downloads":1448,"packageName":null,"latestVersion":"0.2.0","tractionLabel":"1.4K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:58:02.991Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T11:58:02.991Z","lastCrawledAt":"2026-10-10T11:58:02.991Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T11:58:02.991Z","lastVerifiedAt":null,"highlights":[{"version":"0.2.0","createdAt":"2026-07-20T09:12:21.820Z","changelog":"## save-to-spotify v0.2.0 - Added comprehensive onboarding documentation and flow for first-time users ([references/onboarding.md](references/onboarding.md)), enabling guided setup if the user is new or requests onboarding, regardless of existing shows. - Introduced [references/local-preview.md](references/local-preview.md), covering previewing and validating episodes before upload. - Included [references/recipes.md](references/recipes.md) detailing voice and pipeline defaults by content type. - Updated the user interview: streamlined to only ask what is missing, with sensible defaults for language, length, voice, cover image, and companion images. - Expanded installation instructions with clearer Windows support and SmartScreen details. - Removed outdated skill-card documentation; reorganized and updated references for clarity and maintainability.","fileCount":13,"zipByteSize":49978},{"version":"0.1.5","createdAt":"2026-07-17T11:54:34.939Z","changelog":"save-to-spotify 0.1.5 - Removed the sample file skill-card.md to streamline documentation. - Updated references/cli-usage.md with revised or additional CLI instructions and workflows.","fileCount":10,"zipByteSize":35729},{"version":"0.1.4","createdAt":"2026-07-13T15:11:34.768Z","changelog":"save-to-spotify 0.1.4 - References updated for clarity and completeness; SKILL.md was revised. - Timeline reference and CLI usage documentation improved. - Obsolete skill-card.md file removed.","fileCount":10,"zipByteSize":35711},{"version":"0.1.3","createdAt":"2026-06-12T17:40:44.887Z","changelog":"save-to-spotify 0.1.3 - Updated cover image and artwork handling: options now include user-provided, AI-generated, and CDN fallback images with improved typography and RTL font support. - Simplified and clarified cover image selection in the user interview, with explicit fallback order and Pillow compositing guidance. - Expanded [references/cover-image.md] to detail cover path types, typography, and image design rules. - Removed skill-card.md and streamlined documentation references—no impact on production pipeline or CLI usage.","fileCount":10,"zipByteSize":35579},{"version":"0.1.1","createdAt":"2026-05-07T14:44:21.457Z","changelog":"save-to-spotify 0.1.1 - Updated reference documentation in cli-usage.md and timeline.md. - No changes to logic or functionality; this is a documentation update only.","fileCount":10,"zipByteSize":34378},{"version":"0.1.0","createdAt":"2026-05-07T12:39:45.118Z","changelog":"Initial release — introduces audio content production and Spotify save functionality. - Create polished audio episodes with TTS narration and rich timeline, including chapters, images, external links, and Spotify entity companions. - Support for cover image generation: AI-generated (DALL-E, Stable Diffusion), user-provided, or mixed. - Enforce a mandatory user interview to confirm key production preferences before any content is generated. - Show management features: add episodes to new or existing shows, organize saves. - Reference directory included for production rules, CLI usage, Spotify API integration, and content quality guidelines. - Ensures incremental saving, source-to-segment mapping, and respect for third-party rights throughout the pipeline.","fileCount":9,"zipByteSize":32759}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s178q1njn7prgvajksxt46zez58649bp:save-to-spotify","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-spotify-save-to-spotify/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-spotify-save-to-spotify/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-spotify-save-to-spotify/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-spotify-save-to-spotify/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-spotify-save-to-spotify/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-spotify-save-to-spotify/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T14:44:23.781Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-spotify-save-to-spotify/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-spotify-save-to-spotify/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-spotify-save-to-spotify/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-spotify-save-to-spotify/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T11:58:02.991Z","emptyReason":null},"readme":"Skill: Save To Spotify\n\nOwner: spotify\n\nSummary: Create polished audio content and save to Spotify. Produces episodes with TTS narration, a rich timeline (chapters plus in-player images, external links, and...\n\nTags: latest:0.2.0\n\nVersion history:\n\nv0.2.0 | 2026-07-20T09:12:21.820Z | auto\n\n## save-to-spotify v0.2.0\n\n- Added comprehensive onboarding documentation and flow for first-time users ([references/onboarding.md](references/onboarding.md)), enabling guided setup if the user is new or requests onboarding, regardless of existing shows.\n- Introduced [references/local-preview.md](references/local-preview.md), covering previewing and validating episodes before upload.\n- Included [references/recipes.md](references/recipes.md) detailing voice and pipeline defaults by content type.\n- Updated the user interview: streamlined to only ask what is missing, with sensible defaults for language, length, voice, cover image, and companion images.\n- Expanded installation instructions with clearer Windows support and SmartScreen details.\n- Removed outdated skill-card documentation; reorganized and updated references for clarity and maintainability.\n\nv0.1.5 | 2026-07-17T11:54:34.939Z | auto\n\nsave-to-spotify 0.1.5\n\n- Removed the sample file skill-card.md to streamline documentation.\n- Updated references/cli-usage.md with revised or additional CLI instructions and workflows.\n\nv0.1.4 | 2026-07-13T15:11:34.768Z | auto\n\nsave-to-spotify 0.1.4\n\n- References updated for clarity and completeness; SKILL.md was revised.\n- Timeline reference and CLI usage documentation improved.\n- Obsolete skill-card.md file removed.\n\nv0.1.3 | 2026-06-12T17:40:44.887Z | auto\n\nsave-to-spotify 0.1.3\n\n- Updated cover image and artwork handling: options now include user-provided, AI-generated, and CDN fallback images with improved typography and RTL font support.\n- Simplified and clarified cover image selection in the user interview, with explicit fallback order and Pillow compositing guidance.\n- Expanded [references/cover-image.md] to detail cover path types, typography, and image design rules.\n- Removed skill-card.md and streamlined documentation references—no impact on production pipeline or CLI usage.\n\nv0.1.1 | 2026-05-07T14:44:21.457Z | auto\n\nsave-to-spotify 0.1.1\n\n- Updated reference documentation in cli-usage.md and timeline.md.\n- No changes to logic or functionality; this is a documentation update only.\n\nv0.1.0 | 2026-05-07T12:39:45.118Z | user\n\nInitial release — introduces audio content production and Spotify save functionality.\n\n- Create polished audio episodes with TTS narration and rich timeline, including chapters, images, external links, and Spotify entity companions.\n- Support for cover image generation: AI-generated (DALL-E, Stable Diffusion), user-provided, or mixed.\n- Enforce a mandatory user interview to confirm key production preferences before any content is generated.\n- Show management features: add episodes to new or existing shows, organize saves.\n- Reference directory included for production rules, CLI usage, Spotify API integration, and content quality guidelines.\n- Ensures incremental saving, source-to-segment mapping, and respect for third-party rights throughout the pipeline.\n\nArchive index:\n\nArchive v0.2.0: 13 files, 49978 bytes\n\nFiles: references/audio-providers.md (18389b), references/cli-usage.md (15496b), references/content-quality.md (9644b), references/cover-image.md (8239b), references/episode-description.md (2802b), references/local-preview.md (5817b), references/onboarding.md (12585b), references/recipes.md (6087b), references/spotify-api.md (7045b), references/timeline.md (10562b), skill-card.md (3133b), SKILL.md (12546b), _meta.json (134b)\n\nFile v0.2.0:SKILL.md\n\n---\nid: save-to-spotify\nname: save-to-spotify\ndescription: Create polished audio content and save to Spotify. Produces episodes with TTS narration, a rich timeline (chapters plus in-player images, external links, and Spotify entity cards), and a cover image. Also use for raw media saves, show/episode management, and timeline navigation.\nenabled: true\n---\n\n# Audio Content Production Skill\n\n`save-to-spotify` saves audio files to the user's Spotify library. Anything they can play locally — lecture recordings, voice memos, conference talks, language lessons — they can save to Spotify and listen from any device.\n\nShows are folders for organizing saves.\n\nYou are a podcast and audio content production agent. You create polished audio episodes from a variety of sources and formats, produce them with a rich in-player timeline (chapters plus image, link, and Spotify entity companions that appear during playback in the Now Playing View), and save to Spotify.\n\nThis skill defines the **shared production pipeline** — core principles, the user interview checkpoint, and the execution checklist.\n\n## Reference Directory\n\nThese files cover the detailed rules. Load the one you need — don't inline them.\n\n- [references/cli-usage.md](references/cli-usage.md) — Binary install, auth, `upload`/`shows`/`episodes`/`timeline` commands, JSON mode, error handling, troubleshooting, and common end-to-end workflows\n- [references/spotify-api.md](references/spotify-api.md) — Using `developer.spotify.com/llms.txt`, the Spotify Web API OpenAPI spec, and the CLI's token to resolve album / track / artist / playlist / show / episode names to `spotify:...` URIs for `spotify_entity` timeline companions\n- [references/audio-providers.md](references/audio-providers.md) — TTS engine selection, voice config, ffmpeg assembly, silence generation, timeline timestamp calculation\n- [references/cover-image.md](references/cover-image.md) — Cover image paths (user-provided, AI-generated, CDN artwork), typography rules, font & RTL, Pillow compositing recipe\n- [references/timeline.md](references/timeline.md) — Timeline data model, validation rules, companion images (sourced / AI-generated / mixed / skip), including DALL-E / Stable Diffusion code and batch generation\n- [references/episode-description.md](references/episode-description.md) — HTML description format, Python builder from `timeline.json`, formatting rules\n- [references/content-quality.md](references/content-quality.md) — Editorial guidelines: voice, transitions, person context, depth control, visual description, pacing, self-critique\n\n---\n\n## Install\n\nIf `save-to-spotify` is not available on `PATH`, ask the user to confirm CLI installation first, then install it:\n\n```shell\ncurl -fsSL https://saveto.spotify.com/install.sh | bash\n```\n\nOn Windows, run this in **Git Bash** (ships with Git for Windows) — it installs `save-to-spotify.exe` to `~/.local/bin`. The unsigned .exe may trigger a SmartScreen prompt on first run; unblock with `Unblock-File` or right-click → Properties → Unblock.\n\nSee [references/cli-usage.md](references/cli-usage.md) for manual binary downloads, source builds, authentication, command usage, and troubleshooting.\n\n---\n\n## Core Principles\n\n### Read-only. Always.\n\nWhen sourcing content, always respect platform terms of service and robots.txt and third-party IP rights. Use only authorized APIs and user-provided content. Never interact with source platforms beyond reading — do not post, like, follow, or modify content.\n\n### Be the listener's eyes\n\nPodcast listeners can't see anything. You are their eyes. Every piece of visual content — screenshots, images, charts — must be described in the script. If it matters to the segment, say what's in it.\n\n### Deep-link everything\n\nEvery segment in the show notes must link to the original source when possible. A link to a specific moment or post is 10x more valuable than a link to a homepage.\n\n### Respect Third-Party Rights\n\nThe final product must be a noninfringing synthesis of source materials, and must not infringe copyright or other third-party IP rights. It must not mislead as to the source or sponsorship of any material or information.\n\n### Prefer Spotify-native references\n\nWhen a segment points to something that already exists on Spotify — music, podcasts, audiobook titles, artists, albums, playlists, episodes, creators — capture the Spotify URI and use a `spotify_entity` timeline item whenever possible. Prefer the full `spotify:...` URI form, not a bare ID or `open.spotify.com` URL. Use external `link` companions for off-Spotify destinations such as articles, stores, docs, newsletters, and event pages. A `spotify_entity` and a `link` can both appear for the same segment/chapter when both the Spotify destination and the original source are valuable; just place them at non-overlapping times.\n\n### Segment-to-source integrity\n\nThe script has a strict 1:1 mapping: segment [N] corresponds to source item N. This mapping drives chapters, timeline companions, and show notes alignment. Never reorder, merge, or skip segments after assignment.\n\n### Save incrementally\n\nWrite collected data to disk after each sourcing step. If a later step fails, previous work is preserved.\n\n### Pacing and silence\n\nDon't fear strategic silence. Pauses between segments give the listener time to absorb. The 300ms gaps between segments are a minimum — use longer pauses (500ms+) between major topic shifts. Vary the pacing: slow down for important analysis or emotional moments, keep it brisk for roundups and quick hits.\n\n### The user made this\n\nIn every user-facing string, emphasise what the user has created rather than you (the agent) taking credit. Strings should centre the user. For example, instead of \"we created your episode,\" or \"your podcast is ready\", use strings like \"your episode is ready\". Reinforce that this is something the user made.\n\n---\n\n## First-Time Onboarding\n\nUse the streamlined onboarding flow from [references/onboarding.md](references/onboarding.md) instead of the full interview below when **any** of these are true:\n\n1. The user has no shows (`save-to-spotify --json shows` returns an empty `shows` array)\n2. The user says things like \"get started\", \"help me start\", \"first episode\", \"set up\", \"onboard me\", or any phrasing that signals they want the guided experience — **even if they already have shows**\n\nDo NOT check shows first and skip onboarding when the user explicitly asked for the guided flow. The explicit ask always wins.\n\n---\n\n## User Interview\n\n**Chapter-skip playback is NOT an interview question** — never ask about or enable it unprompted; the `configure-chapter-skip` skill owns the trigger rules and workflow.\n\n**Default everything. Only ask what the user's prompt didn't cover.**\n\nMost preferences have sensible defaults — apply them silently. The user's prompt usually provides the content scope; everything else can be defaulted. Do NOT present a numbered list of questions. Do NOT dump all options at once.\n\n### What to default (never ask unless the user brings it up)\n\n- **Language** — user's system locale\n- **Length** — pick from content (briefings ~8min, deep dives ~8min, recaps ~3min)\n- **Voice** — use the configured default from `save-to-spotify tts status --json`. If none is configured, follow the provider selection in [references/audio-providers.md](references/audio-providers.md). On Kokoro, prefer the content type's default voice (the `Kokoro voice` row in [references/recipes.md](references/recipes.md) — e.g. the softer sleep voice for sleep content) over a generic default\n- **Cover image** — AI-generated (see [references/cover-image.md](references/cover-image.md))\n- **Timeline companion images** — mixed (sourced where available, AI-generated fill)\n\n### What to ask (only if not obvious from the prompt)\n\n1. **Content scope** — if the user didn't specify what the episode is about, ask. Otherwise proceed.\n2. **Show** — pick the most relevant existing show by name. If none fits, create one. Only ask if ambiguous.\n\n### Plan confirmation\n\nPresent a one-line plan with choices:\n\n> \"Making a ~8 min deep dive on [topic], adding to [Show Name] with [voice].\"\n\nThen present options:\n- **Go** — start production\n- **Change voice** — pick a different TTS voice\n- **Change length** — shorter or longer\n- **Change topic** — adjust the content scope\n\nAlways guide with choices, never wait for free-text input. Embed whatever the user is judging (plan, chapter list, preview URL) inside the choice prompt itself — text printed before a choice popup can be hidden by it.\n\nIf the user asks to change the skip-forward action (`15 seconds` default vs `Next chapter`), treat it as an explicit request — see the `configure-chapter-skip` skill. Do not start production until the user confirms the plan.\n\n---\n\n## Execution Checklist\n\nEvery episode — regardless of content type — must complete these steps.\n\n0. **Preflight: install, auth, and voice engine** — Run `save-to-spotify --json doctor` before any sourcing. This checks the binary, auth, TTS engines, and ffmpeg in one call. If the binary is missing, ask the user to confirm installation, install it with the command in the Install section after they approve, then run doctor again. If unauthenticated, run `save-to-spotify setup` directly (do not ask the user to run it — just run it). The setup command handles auth + TTS detection in one pass and auto-detects headless environments. **Then confirm a TTS engine is available** via the `tts_engines` field in the doctor output: if one is already set up or the user has a preference, use it; otherwise check for an existing API key (`OPENAI_API_KEY`, `ELEVENLABS_API_KEY`) and suggest that engine first — no install, higher quality. If no key is present, **ask the user** whether to install **Kokoro** (free, local, ~340 MB, [Apache-2.0 licensed](https://raw.githubusercontent.com/hexgrad/kokoro/refs/heads/main/LICENSE)) — put the license link in the question text above the choices, where markdown renders it clickable; never inside option labels, which are plain text. Do not install silently. If they accept, run `save-to-spotify tts setup`. Confirm an engine is *available* before scripting; the interactive voice pick and preview can be deferred until the content is approved — content before audio. Voice previews use the player page in [references/local-preview.md](references/local-preview.md) (\"Voice preview page\"), never auto-play.\n1. **Interview** — Ask the user about preferences, including companion-image source. Present a plan and **wait for confirmation**\n2. **Script** — Present a short chapter overview (compact numbered list, bold chapter names, one line each, no blank lines between items) and get it approved first (revising an outline is free; never dump a full transcript on the user), then write the script following this skill's universal rules (see [references/content-quality.md](references/content-quality.md))\n3. **Critique** — Self-review the script, revise without reordering or removing segments\n4. **Produce** — Generate audio per-segment, concatenate, convert to MP3 (see [references/audio-providers.md](references/audio-providers.md)). Build `timeline.json` with chapters, Spotify entity companions where applicable, image companions with `url` set when image + source belong together, standalone links only for imageless or extra destinations, and additional images as needed (sourced and/or AI-generated per the interview answer) — see [references/timeline.md](references/timeline.md)\n5. **Describe** — Build the timestamped HTML description from the chapter entries in `timeline.json` and source URLs (see [references/episode-description.md](references/episode-description.md))\n6. **Cover image** — Generate or select cover image (square, max 1 MB). **MANDATORY — never skip this step** (see [references/cover-image.md](references/cover-image.md))\n7. **Save** — Start the local browser preview and offer it before saving (serve first, open on request — see [references/local-preview.md](references/local-preview.md)), then save MP3 with title, description, and cover image via `save-to-spotify --json upload` (see [references/cli-usage.md](references/cli-usage.md)). State proactively that the episode is saved private, visible only to the user\n8. **Timeline** — Push `timeline.json` with `timeline set` (uploads image files automatically)\n9. **Verify** — Poll `episodes status` until `READY`\n\nFile v0.2.0:_meta.json\n\n{\n \"ownerId\": \"kn73w4eqhcyrcqet64x9rz87a184g2fx\",\n \"slug\": \"save-to-spotify\",\n \"version\": \"0.2.0\",\n \"publishedAt\": 1784538741820\n}\n\nFile v0.2.0:references/audio-providers.md\n\n# Audio Providers & Assembly\n\nReference for generating speech and assembling audio files for saving via `save-to-spotify`. The user picks their own TTS engine and voice — this documents how to use each one.\n\nTell the user:\n\n> The skill produces audio content that may be distributed via a streaming platform. \n> Every episode must be grounded in content you have the right to reproduce in this form.\n\n## Production pipeline\n\nEvery episode walks the same steps. Recipes define what to write (sourcing, scripting, segment map). This reference covers generation and assembly.\n\n1. Generate TTS audio per segment (one file each for exact chapter timing)\n2. Generate silence files for transitions (300ms minimum between segments, 500ms+ between major shifts)\n3. Concatenate all segments into a single MP3\n4. Normalize volume levels\n5. Calculate chapter timestamps from cumulative segment durations\n6. Build `timeline.json` with chapters, Spotify entity companions, external link companions, and image companions (see [timeline.md](timeline.md))\n\n**Accepted formats:** `.mp3`, `.m4a`, `.wav`, `.ogg` (max 1 GB). Default to `.mp3`. Convert anything else with ffmpeg before upload — see \"Convert formats\" below.\n\n### Voice selection guide\n\n- **Kokoro** (local, free): suggest the recipe's default voice first (the `Kokoro voice` row in [recipes.md](recipes.md)); full voice list in the Kokoro section below\n- **ElevenLabs** (high quality, paid): Amelia, George, Bella\n- **Edge TTS** (free, 300+ voices): `en-US-AriaNeural` (F), `en-US-GuyNeural` (M)\n- **OpenAI TTS** (high quality, paid): `nova`, `alloy`, `echo`, `onyx`\n\n### Multi-voice / bilingual segments\n\nDefault to one voice per episode, but when the content is bilingual, role-played, or otherwise needs multiple voices, use a part-based segment schema and a flattened render manifest.\n\nExample source schema:\n\n```json\n{\n \"segments\": [\n {\n \"title\": \"Swedish intro\",\n \"parts\": [\n {\"lang\": \"sv\", \"voice\": \"sv-SE-SofieNeural\", \"text\": \"Hej och valkommen.\"},\n {\"lang\": \"en\", \"voice\": \"en-GB-LibbyNeural\", \"text\": \"Welcome back to the show.\"}\n ]\n }\n ]\n}\n```\n\nFlatten that into a render manifest before synthesis:\n\n```json\n[\n {\"segment_index\": 0, \"part_index\": 0, \"lang\": \"sv\", \"voice\": \"sv-SE-SofieNeural\", \"text\": \"Hej och valkommen.\", \"out\": \"seg_00_00.mp3\"},\n {\"segment_index\": 0, \"part_index\": 1, \"lang\": \"en\", \"voice\": \"en-GB-LibbyNeural\", \"text\": \"Welcome back to the show.\", \"out\": \"seg_00_01.mp3\"}\n]\n```\n\nConcatenate manifest outputs in order, then compute chapter timestamps from the flattened audio segments.\n\n## Provider selection\n\nWhenever offering Kokoro to the user, include its license — [Apache-2.0](https://raw.githubusercontent.com/hexgrad/kokoro/refs/heads/main/LICENSE) — as a clickable link in the **question text**, where markdown renders. Never put the link inside choice option labels: those render as plain text and the raw URL is unreadable.\n\nWhen a content creation recipe is triggered and no TTS provider has been established, resolve one in this order:\n\n**1. Check for a configured default.** Run `save-to-spotify tts status --json`. If a default engine is set and ready, use it — no questions needed.\n\n**2. Reuse a key the user already has.** If no default is set, `tts status` reports which cloud engines have API keys present. Suggest those first — they're higher quality and need no install:\n\n> You already have an **OpenAI** key set — I can use that with no setup. Prefer that, or a free local voice?\n\n**3. No key? Fall back to Kokoro (the default).**\n\n> No TTS key found, so I'll default to **Kokoro** — a free, local voice engine (no key, no limits, ~340 MB, [Apache-2.0 licensed](https://raw.githubusercontent.com/hexgrad/kokoro/refs/heads/main/LICENSE)). Want that, or pick your own?\n\nIf they accept and Kokoro isn't installed, run `save-to-spotify tts setup` to install it.\n\n**4. Or pick explicitly.** If the user would rather choose:\n\n> Which TTS engine would you like to use? Kokoro is [Apache-2.0 licensed](https://raw.githubusercontent.com/hexgrad/kokoro/refs/heads/main/LICENSE).\n>\n> - **Kokoro** (recommended) -- free, local, no API key, no limits, Apache-2.0\n> - **OpenAI TTS** -- high quality, needs OPENAI_API_KEY\n> - **ElevenLabs** -- most natural, needs ELEVENLABS_API_KEY\n> - Something else? (register any engine with `save-to-spotify tts add`)\n\n### Other providers\n\nThese are fully supported but not front-and-center for new users. See the provider reference below for usage:\n\n- **Edge TTS** (`edge-tts`) -- free, 300+ voices, 70+ languages\n- **Piper** -- offline, fast, open-source\n- **Google Cloud TTS** -- high quality, paid (service account)\n- **gTTS** -- free, Google Translate quality\n- **Amazon Polly** -- cloud, paid\n- **macOS `say`** -- built-in, zero setup, low quality; use only for a quick test\n\nRegister any engine with `save-to-spotify tts add --name --check-cmd `.\n\n### Verification\n\nBefore generating, verify the chosen provider is available:\n\n```shell\nsave-to-spotify tts status --json\n```\n\nThis checks all built-in and custom engines, API keys, and ffmpeg in one call. If a specific engine needs manual verification:\n\n`save-to-spotify --json tts status` is the canonical readiness check. For cloud engines, `ready` means the API key is present — that is all the CLI needs; `tts test` synthesizes previews natively with no Python involved.\n\n**Production synthesis is different**: the full-episode snippets below run through Python, so before generating episode audio (not previews), also verify the packages the chosen snippet imports:\n\n```shell\npython3 -c \"import openai\" # OpenAI production snippet\npython3 -c \"import elevenlabs\" # ElevenLabs production snippet\npython3 -c \"import kokoro_onnx\" # Kokoro (use the venv python — see the Kokoro section)\nffmpeg -version && ffprobe -version # Required for assembly (portable check)\n```\n\nInstall what's missing with pip before synthesis. On Windows the interpreter is `python` (or the `py` launcher), not `python3`. If ffmpeg is missing: `brew install ffmpeg` (macOS), `apt install ffmpeg` (Linux), `winget install ffmpeg` (Windows).\n\nIf nothing is ready, run `save-to-spotify tts setup` to install the free default (Kokoro), or set a cloud TTS API key and run `save-to-spotify tts status` again.\n\n## TTS provider reference\n\n### macOS `say`\n\n```shell\nsay --voice '?' # List voices\nsay -v -o output.m4a --data-format=aac \"Text\" # Generate m4a\nsay -v -o output.m4a --data-format=aac -f in.txt # From file\n```\n\nVoices: `Samantha` (en-US), `Daniel` (en-GB), `Alex` (en-US high quality). Limited languages.\n\n### Edge TTS (recommended free option)\n\n```shell\nedge-tts --list-voices # List all\nedge-tts --voice \"en-US-AriaNeural\" --text \"Hello\" --write-media o.mp3 # Generate\nedge-tts --voice \"en-US-GuyNeural\" -f input.txt --write-media o.mp3 # From file\nedge-tts --voice \"en-US-AriaNeural\" --rate=\"+10%\" --text \"Fast\" --write-media o.mp3 # Faster\nedge-tts --voice \"en-US-AriaNeural\" --rate=\"-30%\" --text \"Slow\" --write-media o.mp3 # Slower\n```\n\nKey voices: `en-US-AriaNeural` (F), `en-US-GuyNeural` (M), `en-GB-SoniaNeural` (F), `en-GB-RyanNeural` (M), `es-ES-ElviraNeural`, `fr-FR-DeniseNeural`, `de-DE-KatjaNeural`, `ja-JP-NanamiNeural`, `zh-CN-XiaoxiaoNeural`.\n\n### OpenAI TTS\n\n```python\nfrom openai import OpenAI\nclient = OpenAI()\nresp = client.audio.speech.create(model=\"tts-1\", voice=\"nova\", input=\"Text\")\nresp.write_to_file(\"output.mp3\")\n```\n\nVoices: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`. Use `tts-1-hd` for higher quality. (Older `stream_to_file` is deprecated in current SDK versions.)\n\n### ElevenLabs\n\n```python\nfrom elevenlabs.client import ElevenLabs\n\nclient = ElevenLabs() # reads ELEVENLABS_API_KEY\n\n# Resolve the voice name to a voice_id first — convert() takes ids, not names.\nvoice_id = next(v.voice_id for v in client.voices.get_all().voices if v.name == \"Rachel\")\n\naudio = client.text_to_speech.convert(\n voice_id=voice_id,\n model_id=\"eleven_multilingual_v2\",\n text=\"Text\",\n)\nwith open(\"output.mp3\", \"wb\") as f:\n for chunk in audio:\n f.write(chunk)\n```\n\nMost natural. Supports multiple languages. (Older `from elevenlabs import generate, save` no longer exists in current SDK versions.)\n\n### Piper (offline)\n\n```shell\necho \"Text\" | piper --model en_US-lessac-medium.onnx --output_file output.wav\nffmpeg -i output.wav -codec:a libmp3lame -qscale:a 2 output.mp3 # convert\n```\n\n### Kokoro (local, free, no API limits)\n\n**Run synthesis with the Kokoro venv's Python, never the system one** — the packages live in the venv. Don't construct the path yourself: read the `kokoro_python` field from `save-to-spotify --json tts status`, which resolves the platform layout (`kokoro-env/bin/python3` on macOS/Linux, `kokoro-env\\Scripts\\python.exe` on Windows).\n\n```python\nfrom kokoro_onnx import Kokoro\nimport soundfile as sf\nimport numpy as np\nimport json\nimport os, glob\n\n# Find kokoro model files — search the save-to-spotify config dir, never hardcode versions\nconfig_dir = os.path.expanduser(\"~/.config/save-to-spotify\")\nsearch_dirs = [os.path.join(config_dir, \"kokoro-env\"), config_dir]\n\ndef find_model(pattern):\n for d in search_dirs:\n hits = glob.glob(os.path.join(d, pattern))\n if hits:\n return sorted(hits)[-1] # latest version\n raise FileNotFoundError(f\"No {pattern} found — run: save-to-spotify tts setup\")\n\nkokoro = Kokoro(find_model('kokoro-v*.onnx'), find_model('voices-v*.bin'))\n\nsegments = [\n (\"Introduction\", intro_text),\n (\"Main Topic\", body_text),\n (\"Sign-off\", outro_text),\n]\n\ntimeline_items = []\nall_samples = []\ncursor_ms = 0\n\nfor title, text in segments:\n samples, sr = kokoro.create(text, voice='af_heart', speed=1.0)\n timeline_items.append({\"chapter\": {\"title\": title, \"start_time_ms\": cursor_ms}})\n all_samples.append(samples)\n # 300ms silence between segments\n silence = np.zeros(int(sr * 0.3))\n all_samples.append(silence)\n cursor_ms += int((len(samples) + len(silence)) / sr * 1000)\n\ncombined = np.concatenate(all_samples)\nsf.write('episode.wav', combined, sr)\n\nwith open('timeline.json', 'w') as f:\n json.dump({\"items\": timeline_items}, f, indent=2)\n```\n\nConvert to MP3: `ffmpeg -i episode.wav -codec:a libmp3lame -b:a 192k episode.mp3`\n\nVoices: `af_heart` (American female, recommended default), `af_nicole` (American female, soft — sleep content), `af_alloy` (American female), `am_adam` (American male), `bf_emma` (British female), `bm_george` (British male). Fully offline, no API limits. Generates audio + chapter timestamps in one pass.\n\n### gTTS (free, basic)\n\n```shell\ngtts-cli \"Text to speak\" --lang en --output output.mp3\ngtts-cli -f input.txt --lang en --output output.mp3\n```\n\n### Google Cloud TTS\n\n```python\nfrom google.cloud import texttospeech\nclient = texttospeech.TextToSpeechClient()\ninput_text = texttospeech.SynthesisInput(text=\"Text\")\nvoice = texttospeech.VoiceSelectionParams(language_code=\"en-US\", name=\"en-US-Neural2-F\")\nconfig = texttospeech.AudioConfig(audio_encoding=texttospeech.AudioEncoding.MP3)\nresp = client.synthesize_speech(input=input_text, voice=voice, audio_config=config)\nwith open(\"output.mp3\", \"wb\") as f:\n f.write(resp.audio_content)\n```\n\n## Text sanitization for TTS\n\nBefore sending text to any TTS engine, clean it:\n\n- Strip markdown: `**bold**` -> `bold`, `# heading` -> `heading`\n- Remove hashtags, emojis, and non-speech artifacts\n- Expand abbreviations that sound wrong when spoken aloud\n- Replace em dashes `—` with hyphens `-` to avoid encoding issues in shell commands\n- Remove URLs from the spoken text (mention them as \"link in the description\" instead)\n\n## Audio assembly with ffmpeg\n\nAll content recipes generate multiple segments that must be joined into a single file; the segment boundaries become chapters in the timeline.\n\nThe snippets below use `/tmp/` and bash syntax (heredocs) for brevity — on Windows, use the session temp directory (`%TEMP%` or Python's `tempfile.gettempdir()`) instead of `/tmp/`, and write file lists with Python or an editor rather than `cat << EOF`.\n\n### Generate silence\n\n```shell\n# 1.5 seconds (transitions between sections)\nffmpeg -f lavfi -i anullsrc=r=44100:cl=mono -t 1.5 -q:a 9 -acodec libmp3lame /tmp/silence_1.5s.mp3\n\n# 3 seconds (recall pauses for language drills)\nffmpeg -f lavfi -i anullsrc=r=44100:cl=mono -t 3 -q:a 9 -acodec libmp3lame /tmp/silence_3s.mp3\n\n# 5 seconds (speaking practice pauses)\nffmpeg -f lavfi -i anullsrc=r=44100:cl=mono -t 5 -q:a 9 -acodec libmp3lame /tmp/silence_5s.mp3\n```\n\n### Concatenate segments\n\n```shell\n# Build a file list (order matters)\ncat > /tmp/segments.txt << 'EOF'\nfile 'segment_01.mp3'\nfile 'silence_1.5s.mp3'\nfile 'segment_02.mp3'\nfile 'silence_1.5s.mp3'\nfile 'segment_03.mp3'\nEOF\n\n# Concatenate — re-encode rather than `-c copy`. Stream-copying small MP3\n# segments yields non-monotonic frame timestamps that `loudnorm` silently\n# drops audio on. The explicit `-ar 44100 -ac 1` also normalizes any stray\n# stereo/48kHz segment to the common format so concat doesn't break.\nffmpeg -f concat -safe 0 -i /tmp/segments.txt -ar 44100 -ac 1 -c:a libmp3lame -b:a 192k /tmp/output.mp3\n```\n\n### Normalize volume\n\nAlways normalize after concatenation — different TTS segments may have different levels:\n\n```shell\nffmpeg -i /tmp/output.mp3 -af loudnorm /tmp/output_normalized.mp3\n```\n\n### Convert formats\n\nIf the TTS outputs a format other than `.mp3`, `.m4a`, `.wav`, or `.ogg`, convert before upload:\n\n```shell\nffmpeg -i input.aiff -codec:a libmp3lame -qscale:a 2 output.mp3\nffmpeg -i input.webm -codec:a libmp3lame -qscale:a 2 output.mp3\n```\n\n### Get segment duration (for timeline timestamps)\n\n```shell\nffprobe -v error -show_entries format=duration -of csv=p=0 segment.mp3\n```\n\n### Timeline timestamp calculation\n\nAfter generating all segments, build `timeline.json` by walking the file list, summing durations for chapter start times, and placing image/link companions inside each chapter's window. The only backend rule for companions is that they do not overlap with each other — chapter windows are independent.\n\n```python\nimport json, subprocess\nfrom pathlib import Path\n\ndef ms(path):\n out = subprocess.check_output(\n ['ffprobe', '-v', 'error', '-show_entries', 'format=duration',\n '-of', 'csv=p=0', str(path)], text=True).strip()\n return int(float(out) * 1000)\n\n# Each segment: (chapter_title, audio_file, companions)\n# companions is a list of dicts:\n# {\"image\": \"img_01_a.jpg\", \"url\": \"...\", \"title\": \"...\"} -- image companion\n# {\"link\": \"https://...\"} -- external link\n# {\"spotify_entity\": \"spotify:track:4uLU6hMCjMI75M1A2tKUQC\"} -- Spotify card\n#\n# When a spotify_entity is used for a track/album/artist, do NOT also add an\n# image companion with that entity's artwork — the card already renders it.\nsegments = [\n (\"Introduction\", \"segment_01.mp3\", []),\n (\"Chapter A\", \"segment_02.mp3\", [\n {\"spotify_entity\": \"spotify:track:4uLU6hMCjMI75M1A2tKUQC\"},\n {\"link\": \"https://example.com/article-1\"},\n ]),\n (\"Chapter B\", \"segment_03.mp3\", [\n {\"image\": \"img_03_a.jpg\", \"url\": \"https://example.com/article-2\", \"title\": \"Source photo\"},\n ]),\n (\"Sign-off\", \"segment_04.mp3\", []),\n]\nsilence_ms = ms('silence_1.5s.mp3')\n\nitems = []\ncursor = 0\nfor title, audio, companions in segments:\n items.append({\"chapter\": {\"title\": title, \"start_time_ms\": cursor}})\n dur = ms(audio)\n # Distribute companions evenly inside the chapter window, with a 500 ms buffer.\n if companions:\n usable = dur - 500 * (len(companions) + 1)\n slot = max(usable // len(companions), 1000)\n for i, c in enumerate(companions):\n start = cursor + 500 + i * (slot + 500)\n duration = slot\n if \"spotify_entity\" in c:\n items.append({\"spotify_entity\": {\"start_time_ms\": start, \"duration_ms\": duration, \"uri\": c[\"spotify_entity\"]}})\n elif \"image\" in c:\n item = {\"image\": {\"start_time_ms\": start, \"duration_ms\": duration, \"image\": c[\"image\"]}}\n if c.get(\"url\"): item[\"image\"][\"url\"] = c[\"url\"]\n if c.get(\"title\"): item[\"image\"][\"title\"] = c[\"title\"]\n items.append(item)\n elif \"link\" in c:\n items.append({\"link\": {\"start_time_ms\": start, \"duration_ms\": duration, \"url\": c[\"link\"]}})\n cursor += dur + silence_ms\n\n# Every chapter's start_time_ms must be strictly less than the assembled\n# audio duration; nothing downstream can verify this.\nfinal_ms = ms('episode.mp3')\nlast_chapter_ms = max(it[\"chapter\"][\"start_time_ms\"] for it in items if \"chapter\" in it)\nassert last_chapter_ms < final_ms, (\n f\"last chapter at {last_chapter_ms} ms >= episode duration {final_ms} ms\"\n)\n\nPath('timeline.json').write_text(json.dumps({\"items\": items}, indent=2))\n```\n\nThe agent passes `timeline.json` to `save-to-spotify --json timeline set --episode-id --from-file timeline.json`. The CLI uploads each local image file to Spotify's image store and swaps the path for the returned upload token before PUT-ing the timeline.\n\n## Standard workflow (used by all recipes)\n\n```\n1. User provides: topic + sources + voice preferences + companion-image source (sourced / AI-generated / mixed / skip)\n2. Agent writes: structured script broken into segments, with source URL(s) and image hint per segment\n3. Agent generates: one audio file per segment via TTS provider\n4. Agent generates: silence files for pauses/transitions\n5. Agent assembles: concatenate segments into single .mp3\n6. Agent normalizes: volume levels\n7. Agent gathers companion images: download from source and/or generate with DALL-E/SD\n8. Agent calculates: chapter timestamps from segment durations\n9. Agent builds: timeline.json with chapters + spotify_entity companions + link companions (source URLs) + image companions\n10. Agent saves: save-to-spotify --json upload ...\n11. Agent sets timeline: save-to-spotify --json timeline set ...\n12. Agent polls: episodes status until READY\n```\n\nRecipes define steps 1-2 (what to write, which URLs and images to gather). This reference covers steps 3-9. The main SKILL.md covers steps 10-12.\n\nFile v0.2.0:references/cli-usage.md\n\n# Save to Spotify\n\n## CLI Usage\n\nReference for the `save-to-spotify` binary: installation, authentication, commands, flags, JSON mode, error handling, and common agent workflows.\n\n## Installation\n\n### One-line install (recommended)\n\n```shell\ncurl -fsSL https://saveto.spotify.com/install.sh | bash\n```\n\nDetects OS and architecture, downloads the binary from GitHub Releases, verifies the SHA256 checksum, and installs to `/usr/local/bin` (or `~/.local/bin` if not writable).\n\nPin a version or change the install directory:\n\n```shell\n# Specific version\ncurl -fsSL https://saveto.spotify.com/install.sh | bash -s -- --version 0.2.0\n\n# Custom directory\ncurl -fsSL https://saveto.spotify.com/install.sh | bash -s -- --dir ~/.local/bin\n\n# Via environment variables\nSAVE_TO_SPOTIFY_VERSION=0.2.0 SAVE_TO_SPOTIFY_INSTALL_DIR=~/.local/bin \\\n curl -fsSL https://saveto.spotify.com/install.sh | bash\n```\n\n### Download a binary manually\n\nGrab the latest release for the platform from [releases](https://github.com/spotify/save-to-spotify/releases):\n\n```shell\n# macOS Apple Silicon\ngh release download --repo spotify/save-to-spotify --pattern \"save-to-spotify-darwin-arm64\"\nchmod +x save-to-spotify-darwin-arm64\nsudo mv save-to-spotify-darwin-arm64 /usr/local/bin/save-to-spotify\n\n# macOS Intel\ngh release download --repo spotify/save-to-spotify --pattern \"save-to-spotify-darwin-amd64\"\nchmod +x save-to-spotify-darwin-amd64\nsudo mv save-to-spotify-darwin-amd64 /usr/local/bin/save-to-spotify\n\n# Linux x86_64\ngh release download --repo spotify/save-to-spotify --pattern \"save-to-spotify-linux-amd64\"\nchmod +x save-to-spotify-linux-amd64\nsudo mv save-to-spotify-linux-amd64 /usr/local/bin/save-to-spotify\n```\n\n### Build from source\n\nRequires Go 1.21+.\n\n```shell\ngit clone https://github.com/spotify/save-to-spotify.git && cd save-to-spotify\ngo build -ldflags \"-X github.com/spotify/save-to-spotify/cmd.commit=$(git rev-parse --short HEAD)\" \\\n -o save-to-spotify .\nsudo mv save-to-spotify /usr/local/bin/\n```\n\nVerify installation:\n\n```shell\nsave-to-spotify version\n```\n\n## First-run setup\n\nAfter installation, run the guided setup to authenticate and detect TTS engines:\n\n```shell\nsave-to-spotify setup\n```\n\nThis handles auth + TTS detection in one pass. It auto-detects headless environments and uses the appropriate auth flow. After setup, verify everything is ready:\n\n```shell\nsave-to-spotify doctor\n```\n\nReports binary, auth, TTS engines, and ffmpeg status. In JSON mode (`--json`), returns a structured report for agents to use as a preflight check.\n\n## TTS engine management\n\nThe CLI detects and manages TTS engines used for audio generation:\n\n```shell\n# Check which engines are available\nsave-to-spotify tts status\n\n# Install Kokoro (free, local, no API key)\nsave-to-spotify tts setup\n\n# Install or configure a specific engine\nsave-to-spotify tts setup --engine openai\n\n# List voices for an engine\nsave-to-spotify tts voices --engine kokoro\n\n# Test a voice with a sample phrase\nsave-to-spotify tts test --engine kokoro --voice af_heart\n\n# Get or set the default engine\nsave-to-spotify tts default\nsave-to-spotify tts default openai\n\n# Register a custom engine\nsave-to-spotify tts add --name gemini --check-cmd 'python3 -c \"import google.genai\"' --key-env GEMINI_API_KEY # use python instead of python3 on Windows\n\n# Remove a custom engine\nsave-to-spotify tts remove gemini\n```\n\nThree engines are built-in: **Kokoro** (free, local), **OpenAI TTS**, and **ElevenLabs**. Register any additional engine with `tts add`.\n\n## Authentication\n\nThe user must authenticate once before any save. The CLI uses OAuth 2.0 with PKCE -- no client secret needed.\n\n### Interactive (user has a browser)\n\n```shell\nsave-to-spotify auth login\n```\n\nThis opens the browser, the user approves, and a token is saved to `~/.config/save-to-spotify/token.json` (this path holds on every platform, including Windows — `%USERPROFILE%\\.config\\...` — the CLI does not use APPDATA).\n\n### Headless (remote server, CI, or agent environment)\n\n```shell\nsave-to-spotify auth login --no-browser\n```\n\nThis prints an authorization URL. The user visits it in any browser, approves, and pastes the redirect URL back into the terminal. The redirect URL will look like `http://127.0.0.1:8085/callback?code=...&state=...` -- it's fine if the page shows a connection error, the URL itself is what matters.\n\n### Environment token (skip OAuth entirely)\n\nIf the user already has a Spotify access token (e.g. from another tool or CI secret):\n\n```shell\nexport SAVE_TO_SPOTIFY_AUTH_TOKEN=\"BQD...\"\n```\n\nWhen this env var is set, the CLI uses it directly with no file I/O and no token refresh. The token must be kept fresh externally.\n\n### Check auth status\n\n```shell\nsave-to-spotify --json auth status\n```\n\nReturns `{\"authenticated\": true, \"token_valid\": true, ...}` or `{\"authenticated\": false}`.\n\nToken refresh is automatic -- if the saved token is expired, the CLI refreshes it silently on the next command. No action needed unless the refresh token itself is revoked, in which case the user must `auth login` again.\n\n### Print the access token\n\n```shell\nsave-to-spotify token\n```\n\nPrints the current access token to stdout -- directly usable as a **Spotify Web API bearer** for requests against `api.spotify.com`. Useful for catalog lookups (searching album/track URIs, fetching release metadata) from inside recipes. Exits non-zero and prints a diagnostic to stderr when the stored token cannot be refreshed. Always check the exit code before piping into an `Authorization` header -- otherwise an empty token produces a misleading HTTP 400 from Spotify rather than a clean auth error.\n\nSee [spotify-api.md](spotify-api.md) for the official `developer.spotify.com` references, OpenAPI spec URL, endpoint patterns, and URI-resolution helpers.\n\n## Saving media\n\n### Quick save (recommended for most cases)\n\nThe `upload` command is the simplest path -- one command to create an episode and save the file:\n\n```shell\nsave-to-spotify --json upload recording.mp3 \\\n --title \"My Recording\" \\\n --summary \"Description here\" \\\n --image cover.jpg\n```\n\nOutput:\n```json\n{\"episode_uri\": \"spotify:episode:abc123\", \"title\": \"My Recording\", \"status\": \"PROCESSING\"}\n```\n\nIf the user has no shows yet, one is auto-created as \"My Podcast\".\n\n### Save to a specific show\n\n```shell\nsave-to-spotify --json upload lecture.m4a \\\n --title \"Lecture 3: Distributed Systems\" \\\n --summary \"CS 307 Spring 2024\" \\\n --show-id spotify:show:xyz789 \\\n --image cover.jpg\n```\n\nWhen `--show-id` is omitted, the CLI uses the most recently created show.\n\n### Create a new show and save in one step\n\n```shell\nsave-to-spotify --json upload keynote.mp3 \\\n --title \"2024 Keynote\" \\\n --summary \"Opening talk by \" \\\n --new-show \"Conference Talks\" \\\n --image cover.jpg\n```\n\n`--new-show` and `--show-id` are mutually exclusive.\n\n### Granular episode creation\n\nFor more control, use `episodes create` instead of `upload`:\n\n```shell\nsave-to-spotify --json episodes create \\\n --title \"Episode Title\" \\\n --file audio.mp3 \\\n --summary \"Episode description\" \\\n --show-id spotify:show:xyz789 \\\n --image episode-cover.jpg \\\n --language en\n```\n\nThe difference: `episodes create` requires `--summary` and `--file` as explicit flags (not positional), and does not support `--new-show`.\n\n## Supported file formats\n\n| Extension | Type | MIME |\n|-----------|------|------|\n| `.mp3` | Audio | `audio/mpeg` |\n| `.m4a` | Audio | `audio/mp4` |\n| `.wav` | Audio | `audio/wav` |\n| `.ogg` | Audio | `audio/ogg` |\n\n**Maximum file size: 1 GB.**\n\n## Managing shows\n\nShows are folders that group episodes. Every episode belongs to exactly one show.\n\n```shell\n# List all shows\nsave-to-spotify --json shows\n\n# Create a show (always include --image)\nsave-to-spotify --json shows create --title \"My Lectures\" --summary \"University recordings\" --image cover.jpg\n\n# Get show details\nsave-to-spotify --json shows get \n\n# Delete a show (and all its episodes)\nsave-to-spotify --json shows delete \n```\n\n`save-to-spotify --json shows` should be the first show-management command you run. Check what already exists before creating a new show.\n\n### Playback control\n\n`shows create` accepts `--playback-control ` (currently `chapter-skip`) to set a show's skip-forward behavior at creation time. The response includes `playback_control` only when the backend applied the setting — if the field is absent, the value was dropped and the show has default controls. For behavior, constraints, and when to enable it, defer to the `configure-chapter-skip` skill.\n\n## Managing episodes\n\n```shell\n# List episodes in a show\nsave-to-spotify --json episodes --show-id \n\n# Check episode readiness\nsave-to-spotify --json episodes status \n\n# Delete an episode\nsave-to-spotify --json episodes delete \n```\n\nShow and episode metadata is immutable after creation. To change a title or description, delete and re-create.\n\n### Episode readiness\n\nAfter saving, poll for readiness before sharing:\n\n```shell\nsave-to-spotify --json episodes status \n```\n\nOutput:\n```json\n{\"episode_uri\": \"spotify:episode:abc123\", \"readiness\": \"READY\"}\n```\n\nReadiness values:\n- `READY` -- playable on Spotify\n- `PROCESSING` -- still being processed (wait and retry)\n- `FAILED` -- processing failed; check the episode metadata and re-save if needed\n\nMost episodes are ready within 1-2 minutes. For large files, allow up to 5 minutes.\n\n## IDs and URIs\n\nThe CLI accepts both bare IDs and full Spotify URIs interchangeably, but agents should prefer the full Spotify URI form whenever possible:\n- `abc123def456` (bare ID)\n- `spotify:show:abc123def456` (full URI)\n\nJSON output always includes the full URI form.\n\n## JSON mode\n\n**Always use `--json` when operating as an agent.** It must appear before the command:\n\n```shell\nsave-to-spotify --json [flags]\n```\n\nIn JSON mode:\n- All output is valid JSON on stdout\n- Errors are `{\"error\": \"message\"}` on stdout with exit code 1\n- Progress bars and activity indicators are suppressed\n- Informational messages to stderr are suppressed\n\nWithout `--json`, output is human-readable text.\n\n## Timeout control\n\nThe default API timeout is 30 seconds. For large file uploads, the upload itself has no timeout (separate HTTP client), but the episode creation API call does. Override if needed:\n\n```shell\nsave-to-spotify --json --timeout 2m upload large-recording.mp3 --title \"Long Episode\" --image cover.jpg\n```\n\nOr via environment variable:\n```shell\nexport SAVE_TO_SPOTIFY_TIMEOUT=2m\n```\n\n## Common agent workflows\n\nThese snippets use bash syntax (command substitution, `while` loops, parameter expansion). On Windows, run them in Git Bash or translate to PowerShell/Python — don't paste them into cmd or PowerShell as-is.\n\n### Create a rich-timeline episode end-to-end\n\n```shell\n# 1. Generate cover image (MANDATORY — see cover-image.md)\npython3 generate_cover.py\n\n# 2. Save with cover image\nRESULT=$(save-to-spotify --json upload episode.mp3 \\\n --title \"Daily Digest - April 15, 2026\" \\\n --summary \"$(cat description.txt)\" \\\n --image cover.jpg)\nEP_URI=$(echo \"$RESULT\" | jq -r .episode_uri)\nEP_ID=${EP_URI#spotify:episode:}\n\n# 3. Set timeline (chapters + image/link/Spotify companions in one call)\nsave-to-spotify --json timeline set --episode-id \"$EP_ID\" --from-file timeline.json\n\n# 4. Poll until ready\nwhile true; do\n STATUS=$(save-to-spotify --json episodes status \"$EP_ID\" | jq -r .readiness)\n [ \"$STATUS\" = \"READY\" ] && break\n [ \"$STATUS\" = \"FAILED\" ] && echo \"Processing failed\" && exit 1\n sleep 15\ndone\n\necho \"Episode ready: $EP_URI\"\n```\n\n### Save a single file\n\n```shell\nURI=$(save-to-spotify --json upload recording.mp3 --title \"My Recording\" --summary \"A recording\" --image cover.jpg | jq -r .episode_uri)\nEP_ID=${URI#spotify:episode:}\n\nwhile true; do\n STATUS=$(save-to-spotify --json episodes status \"$EP_ID\" | jq -r .readiness)\n [ \"$STATUS\" = \"READY\" ] && break\n [ \"$STATUS\" = \"FAILED\" ] && echo \"Processing failed\" && exit 1\n sleep 15\ndone\n```\n\n### Batch save multiple files to one show\n\n```shell\nSHOW_URI=$(save-to-spotify --json shows create --title \"Conference Talks 2024\" --image show-cover.jpg | jq -r .show_uri)\n\nfor f in talks/*.mp3; do\n TITLE=$(basename \"$f\" .mp3 | tr '-' ' ')\n save-to-spotify --json upload \"$f\" --title \"$TITLE\" --summary \"Conference talk\" --show-id \"$SHOW_URI\" --image cover.jpg\ndone\n```\n\n## Error handling\n\nWith `--json`, every command returns exit code 0 on success and exit code 1 on error. Errors are returned as `{\"error\": \"message\"}`. **Always check for errors after each command.**\n\n```bash\nRESULT=$(save-to-spotify --json upload episode.mp3 --title \"My Episode\" --image cover.jpg)\nif echo \"$RESULT\" | jq -e .error > /dev/null 2>&1; then\n echo \"Failed: $(echo \"$RESULT\" | jq -r .error)\"\n exit 1\nfi\nEP_URI=$(echo \"$RESULT\" | jq -r .episode_uri)\nEP_ID=${EP_URI#spotify:episode:}\n\nwhile true; do\n STATUS=$(save-to-spotify --json episodes status \"$EP_ID\")\n READINESS=$(echo \"$STATUS\" | jq -r .readiness)\n [ \"$READINESS\" = \"READY\" ] && break\n [ \"$READINESS\" = \"FAILED\" ] && echo \"Processing failed\" && exit 1\n sleep 15\ndone\n```\n\nCommon errors:\n\n| Error | Cause | Action |\n|-------|-------|--------|\n| `not authenticated` | No token file | Run `auth login` |\n| `token refresh failed` | Refresh token revoked | Run `auth login` again |\n| `unsupported file extension` | Wrong file type | Convert to a supported format |\n| `file too large` | Over 1 GB | Compress or split the file |\n| `image too large` | Over 1 MB | Resize the image |\n| `API error (429)` | Rate limited | Wait and retry after a delay |\n| `API error (401)` | Token expired mid-request | Retry (auto-refresh will kick in) |\n| `API error (403)` | Insufficient permissions | Re-authenticate with `auth login` |\n| `--new-show and --show-id are mutually exclusive` | Conflicting flags | Use one or the other |\n\n## Troubleshooting\n\n### Episode not appearing after saving\nUse `episodes status ` to check readiness. Processing can take a few minutes after the save completes.\n\n### Image upload fails\nImages must be `.jpg`, `.jpeg`, or `.png`, max 1 MB, with valid magic bytes (actual JPEG/PNG content, not just a renamed file).\n\n### \"unsupported file extension\" error\nOnly `.mp3`, `.m4a`, `.wav`, and `.ogg` are supported. Convert other formats first (e.g., `ffmpeg -i input.webm output.mp3`).\n\n## Environment variables reference\n\n| Variable | Purpose |\n|----------|---------|\n| `SAVE_TO_SPOTIFY_AUTH_TOKEN` | Bearer token; skips OAuth entirely (no refresh, no expiry tracking) |\n| `SAVE_TO_SPOTIFY_BACKEND_URL` | Override backend URL |\n| `SAVE_TO_SPOTIFY_TIMEOUT` | API timeout duration (e.g. `30s`, `2m`) |\n\n## Content policy\n\n- **No copyrighted music:** Content that is classified as music by Spotify's moderation system will be taken down.\n- **Moderation applies:** Standard Spotify podcast moderation policies apply. Content that violates policies will be removed and the user will be notified via email.\n- **No sensitive data:** Do not save content containing passwords, credentials, PII of others, or confidential business information. The content is stored on Spotify's servers.\n- **Save limits apply:** There are per-user rate limits on saves (per hour and per week). If a limit is hit, the API returns an error -- wait and retry later.\n- **Never fabricate URLs:** Every source link in episode descriptions must come from actual content sourcing. If a URL isn't found, omit the link -- never invent one.\n\nFile v0.2.0:references/content-quality.md\n\n# Content Quality & Editorial Guidelines\n\nReference for writing scripts that sound good when spoken aloud. Applies to all content recipes. Audio content has different constraints than written content — these guidelines encode production learnings from hundreds of generated episodes.\n\n## The golden rule: write for the ear\n\nText is forgiving. Readers can re-read a sentence, scan ahead, or slow down. Audio is linear and unforgiving — if the listener misses something, it's gone. Every line must land on first hearing.\n\n## Voice and tone\n\n### Match voice to format\n\n| Format | Voice | Energy |\n|--------|-------|--------|\n| Factual summary | Sharp analyst | Confident, declarative, varied energy per segment |\n| Travel guide | Well-traveled friend | Conversational, specific, enthusiastic but honest |\n| Explainer | Patient teacher | Clear, builds from simple to complex |\n| Daily briefing | Briefing companion | Brisk, clear, energetic |\n| Language lesson | Encouraging tutor | Patient, repetitive, affirming |\n\n### Universal voice principles\n\n- **Declarative beats tentative.** \"This matters because...\" not \"This could potentially be interesting...\"\n- **Concrete beats abstract.** \"They're trying to lock in developers\" not \"they're enhancing ecosystem engagement\"\n- **Short beats long.** Mix short punchy sentences with longer analytical ones. Never more than two long sentences in a row\n- **Active beats passive.** \"Sweden cut Chinese research ties\" not \"Chinese research ties were cut by Sweden\"\n- **Specific beats vague.** \"Expect to pay 15 euros for a main course\" not \"food is reasonably priced\"\n\n## Transitions between segments\n\nThis is the single most important audio production skill. **Listeners cannot see segment boundaries.** Without clear verbal signals, segments blur together into mush.\n\nEvery segment must open with a clear transition. Vary these — using the same transition every time is as bad as having none:\n\n- **Subject lead:** \"Keychron just open-sourced their hardware...\" / \"The housing market is shifting...\"\n- **Framing hooks:** \"This is huge.\" / \"Here's what caught my eye.\" / \"Quick note:\"\n- **Topic shifts:** \"On the security side...\" / \"Turning to the economy...\"\n- **Related bridges:** \"That same dynamic is playing out in...\"\n- **Simple transitions:** \"Moving on.\" / \"Meanwhile...\" / \"Next up...\"\n- **Travel transitions:** \"From there, head south to...\" / \"After lunch, the plan takes you to...\"\n- **Time markers:** \"Back in 1927...\" / \"Fast forward to today...\"\n\n## Person context\n\nWhen introducing someone by name, briefly explain WHO they are. Listeners don't have hyperlinks — they can't look someone up mid-sentence.\n\n- \"Marie Curie, the first person to win Nobel Prizes in two sciences...\"\n- \"Ada Lovelace, the 19th-century mathematician often called the first computer programmer...\"\n- \"John Constable, one of England's greatest landscape painters...\"\n\nOne clause, not a bio. If the person isn't well-known, anchor them to something the listener knows, but with well-grounded facts.\n\n## Depth control\n\nNot every item deserves equal time. Classify content by importance and adjust depth accordingly:\n\n| Tier | Sentences | Approach |\n|------|-----------|----------|\n| **A** (major) | 4-6 | What happened → strategic significance → added context → implication |\n| **B** (notable) | 3-4 | What happened → why interesting → one sentence context |\n| **C** (brief) | 1 | State the fact, move on. No analysis, no context |\n\nUse Tier C aggressively for: thin engagement-bait, celebrity amplification with no insight, opinion with no new information, promotional announcements. High engagement alone does NOT justify a high tier.\n\n## Default-off content categories\n\nThese skills MUST NOT produce:\n\n- Instructions for self-harm or suicide methods\n- Instructions for drug synthesis, weapon construction, or similar harmful material\n- Sexually explicit content\n- Sexual content involving minors\n- Promotion or celebration of violent extremism\n- Instructions for harming others\n- Targeted harassment content involving real individuals\n\n## Sensitive-topic checkpoint\n\nSome topics deserve an explicit \"are you sure?\" before producing an authoritative-sounding episode. If the topic, source set, or destination touches:\n\n- Named living individuals' alleged misconduct\n- Active political, religious, or cultural controversy\n- Advisory content (medical treatment, investment decisions, legal processes)\n\n— restate the planned angle and wait for explicit *go*. Not a refusal; a confirmation. Advisory topics also get a \"not professional advice — consult a qualified source\" line in both script and description.\n\n## Describing visual content\n\nPodcast listeners can't see anything. **You are their eyes.** When the source material is visual (images, charts, GIFs, screenshots):\n\n- Describe what's happening: \"A ring of rotating blades spirals around the log, stripping bark in ribbons\"\n- Include emotional reaction: \"It's almost hypnotic to watch\"\n- Reference the source: \"In a post on Example Site this week...\"\n- Mention where to see it: \"Link to the original is in the show notes\"\n\nNever skip describing visual content — if it matters to the segment, say what's in it.\n\n## Things to AVOID\n\nThese patterns make AI-generated audio content sound generic and robotic:\n\n- **\"Let's dive in\"** / \"Without further ado\" / \"Buckle up\" — cliché openings\n- **\"garnering over X likes\"** / \"racking up views\" — engagement metrics as filler\n- **Starting a segment with someone's full display name** as the literal first word\n- **Metrics without meaning** — only mention numbers when they're remarkable relative to context\n- **Press-release language** — \"We're thrilled to announce\" / \"innovative solutions\"\n- **Brochure language** — \"A hidden gem\" / \"A must-visit destination\" / \"Something for everyone\"\n- **Trailing summaries** — don't recap what you just said. The listener heard it\n- **Equal-time syndrome** — not every item needs the same depth. Be ruthless about tier assignment\n- **Verbatim reproduction of sources** — paraphrase the substance. Direct quotes stay under two sentences and are labeled (\"as the article puts it...\")\n\n## Pacing and silence\n\nDon't fear strategic silence. Pauses between segments give the listener time to absorb.\n\n- **300ms** — minimum gap between segments within a section\n- **500ms+** — between major topic shifts or chapter boundaries\n- **1-2 seconds** — before a significant reveal or after an emotional moment\n- **3-5 seconds** — for active recall pauses (flashcards, language drills)\n\nVary the pacing within segments too: slow down for important analysis or emotional moments, keep it brisk for roundups and minor items.\n\n## Self-critique checklist\n\nAfter drafting any script, evaluate against these criteria:\n\n1. **Does each segment explain WHY, not just WHAT?** (digests) / **Is each stop actually useful?** (travel)\n2. **Does the voice stay consistent throughout?** No sudden shifts from casual to formal\n3. **Does each segment clearly signal a transition?** Read the first sentence of each segment aloud — could a listener tell a new topic started?\n4. **Is the pacing varied?** Important parts get more space, minor ones stay brief\n5. **Would this sound natural read aloud?** Read it out loud. If you stumble, rewrite\n6. **Are sources attributed naturally?** \"According to...\" not footnotes\n7. **Is visual content described?** For every image referenced, does the script say what's in it?\n\nThe critique must NEVER suggest cutting or removing any segment — segment-to-source integrity is sacred. Instead, suggest how to improve the segment's framing, analysis, or writing.\n\n## Source linking\n\nEvery piece of source content should have its original URL captured and preserved through the pipeline. The URL appears in the episode description as a clickable link.\n\n- **An episode without source links is significantly less useful** — listeners learn about a segment but can't follow up\n- **Never fabricate URLs** — if a URL isn't found, omit the link\n- **Never fabricate facts** — if you can't verify a claim and aren't genuinely confident, skip it or say \"the sources don't cover this.\" Applies to quotes, statistics, dates, studies, and prices. Same posture as \"Never fabricate URLs\", extended\n- **AI-generated disclosure** — end every description with a content-describing line: *\"AI-narrated audio assembled from the sources in this description\"* or, for knowledge-only episodes, *\"AI-narrated audio — verify key facts before acting.\"*\n- **Label links by platform:** \"read on Example\", \"see on Example.org\", \"visit site\"\n- **Front-load the description summary** — the first 1-2 sentences show as a preview in podcast apps. Don't waste them on boilerplate\n\n## Episode naming\n\n- **Show name:** Short, memorable, searchable. Avoid generic names that get lost in search results\n- **Episode title:** Include the date or episode number for recurring shows. Keep under ~60 characters to avoid truncation\n- **Consistent format:** Pick a pattern and stick with it: \"Show Name - Date\", \"Show Name: Topic\"\n\n## Episode length\n\nMatch length to content density — don't pad to hit a target:\n\n| Format | Typical length |\n|--------|---------------|\n| Daily digest | 3-6 min |\n| Weekly digest | 5-10 min |\n| Short fiction | 5-15 min |\n| Travel guide (per trip) | 5-10 min |\n| Deep dive / explainer | 15-30 min |\n| Daily briefing | 5-12 min |\n| Language lesson | 10-20 min |\n\nAI-narrated content is denser than conversational podcasts — listeners absorb it faster. A tight 4-minute episode with strong content beats a padded 10-minute one.\n\nFile v0.2.0:references/cover-image.md\n\n# Cover Image\n\n**Every show & every episode MUST have a cover image.** Never save without `--image`.\n\n**Format:** JPG or PNG, max 1 MB, 1400x1400 square.\n\n## Paths (priority order)\n\n1. **User-provided** — only when user supplies an image file. Skip otherwise. Resize to 1400x1400, apply strong overlay, add typography (unless user opts out).\n2. **AI-generated** — default when a known image generation API is available (DALL-E, Stable Diffusion). Never use unvetted services. No overlay (prompt reserves negative space).\n3. **CDN artwork** — terminal fallback. No overlay (built-in legibility). Always available, cannot fail.\n\n**Fallthrough:** AI fails → CDN. CDN is the terminal fallback.\n\n### Path 1: User-provided\n\n**Skip this path entirely if the user did not provide an image file.** Do not generate a substitute image — proceed to Path 2.\n\nAccept JPG/PNG at any aspect ratio. Reject if below 600x600 or corrupted. Crop to square, resize to 1400x1400, compress to <1 MB (JPG 90%). Apply strong overlay, then add typography unless user opts out.\n\n**Never:** apply filters, AI enhancement, generate a stand-in image, or override with an agent-generated image.\n\n### Path 2: AI-generated (default)\n\n**Only use known image generation APIs:** DALL-E (OpenAI), Stable Diffusion, or Midjourney. Never use unvetted services (e.g., pollinations.ai) — quality is unreliable and licensing unclear. If no known API key is available, skip to CDN (Path 3).\n\n**Never render text with the model** — composite with Pillow afterwards.\n\n**Prompt pattern:** `\"{style} of {concrete subject}, {composition}, {palette}, square composition, negative space in lower third, no text, no logos\"`\n\nExample: topic \"Weekly Stockholm news briefing\" → `\"Minimalist illustration of a Stockholm rooftop skyline at dusk, muted blue-grey palette, square composition, negative space in lower third, no text, no logos\"`\n\n**Every prompt must include:** a specific concrete subject (not a concept), a composition direction, a palette descriptor, \"square composition\", \"negative space in lower third\", \"no text, no logos\".\n\n**Style:** photorealistic or clean illustration only. No collage, 3D renders, faces, or AI-generated likenesses.\n\n**Never produce:** podcast-meta imagery (mics, headphones), stock cliches (handshakes, lightbulbs), neon/HDR, baked-in text or logos.\n\n**Skip AI if:** topic is abstract, involves real named people, refers to events after the model's training cutoff, or user requested otherwise.\n\nSee [timeline.md](timeline.md) for DALL-E / Stable Diffusion code examples.\n\n### Path 3: CDN artwork (terminal fallback)\n\nPre-designed base artwork with Pillow typography. No overlay needed. 20 variants (`uts-01.png` through `uts-20.png`), selected by hash of show name. Always available, cannot fail.\n\n**CDN endpoint:** `https://save-to-spotify.spotifycdn.com/assets/uts-{01..20}.png`\n\n## Typography\n\n**Mandatory** on every cover (unless user opted out in Path 1). Always composited with Pillow. Never rely on AI text rendering.\n\n**Default copy:** show name only. Add date/episode number only to disambiguate >1 episode per day.\n\n### Constraints\n\n- **One label only.** No subtitles, taglines, or descriptors.\n- **Max 3 lines.** If title doesn't fit, shorten: drop articles, use short forms. Full title preserved in metadata — surface shortened title to user & offer to regenerate.\n- **No widows.** Don't strand a single short word on its own line.\n- **Break on meaning.** Keep concepts together. Pick the split producing the most balanced line widths.\n\n### Font & RTL\n\n| Script | Font | Alignment |\n| --- | --- | --- |\n| Latin (default) | **Montserrat Bold** | bottom-left |\n| Arabic | **Tajawal Bold** | bottom-right |\n| Hebrew | **Noto Sans Hebrew Bold** | bottom-right |\n\nAll OFL-licensed Google Fonts. Downloaded and cached on first use (`~/.cache/save-to-spotify/fonts/`). Bold or heavier only. Never system defaults or decorative fonts.\n\n**RTL detection:** if any character has `unicodedata.bidirectional(ch) in ('R', 'AL', 'AN')`, use RTL font and right-alignment.\n\n**No reshaper libraries.** Do NOT use `arabic_reshaper` or `python-bidi` — modern fonts handle shaping natively in Pillow.\n\n### Colour & effects\n\n- **White text only.** No accent colours, no exceptions.\n- **No text effects.** No drop shadows, strokes, outlines, glows.\n\n## Pillow compositing recipe\n\nConstants and thresholds are authoritative — see code below for exact values.\n\n```python\nfrom PIL import Image, ImageDraw, ImageFont\nimport os, hashlib, unicodedata, urllib.request\n\nCANVAS = 1400\nMARGIN = 64\nMAX_TEXT_WIDTH = int((CANVAS - 2 * MARGIN) * 0.85)\nMAX_TEXT_HEIGHT = CANVAS - MARGIN - CANVAS // 2 # 636px\nMIN_FONT_SIZE = 100\nMAX_FONT_SIZE = 400\nLEADING_FACTOR = 0.97\n\nFONT_CACHE = os.path.join(os.path.expanduser(\"~\"), \".cache\", \"save-to-spotify\", \"fonts\")\nFONTS = {\n \"latin\": (\"Montserrat-Bold.ttf\", \"https://raw.githubusercontent.com/JulietaUla/Montserrat/master/fonts/ttf/Montserrat-Bold.ttf\"),\n \"arabic\": (\"Tajawal-Bold.ttf\", \"https://raw.githubusercontent.com/google/fonts/main/ofl/tajawal/Tajawal-Bold.ttf\"),\n \"hebrew\": (\"NotoSansHebrew-Bold.ttf\", \"https://raw.githubusercontent.com/google/fonts/main/ofl/notosanshebrew/NotoSansHebrew-Bold.ttf\"),\n}\n\ndef detect_script(title):\n for ch in title:\n if '؀' <= ch <= 'ۿ' or 'ݐ' <= ch <= 'ݿ': return \"arabic\"\n if '֐' <= ch <= '׿': return \"hebrew\"\n return \"latin\"\n\ndef load_font(size, title=\"\"):\n os.makedirs(FONT_CACHE, exist_ok=True)\n fname, url = FONTS[detect_script(title)]\n path = os.path.join(FONT_CACHE, fname)\n if not os.path.exists(path):\n urllib.request.urlretrieve(url, path)\n return ImageFont.truetype(path, size)\n\ndef measure_line(font, text):\n if not text: return (0, 0)\n b = font.getbbox(text)\n return b[2] - b[0], b[3] - b[1]\n\ndef _split_combos(words, n):\n if n == 1: yield [words]; return\n for i in range(1, len(words) - n + 2):\n for rest in _split_combos(words[i:], n - 1):\n yield [words[:i]] + rest\n\ndef break_lines(title, font):\n words = title.split()\n if not words: return [title]\n best, best_d = None, float(\"inf\")\n for n in range(1, min(len(words), 3) + 1):\n for combo in _split_combos(words, n):\n lines = [\" \".join(p) for p in combo if p]\n if not lines: continue\n ws = [measure_line(font, l)[0] for l in lines]\n if max(ws) > MAX_TEXT_WIDTH: continue\n d = max(ws) - min(ws)\n if d < best_d: best_d, best = d, lines\n return best or [title]\n\ndef fit_title(title):\n if not title: title = \"Untitled\"\n for sz in range(MAX_FONT_SIZE, MIN_FONT_SIZE - 1, -2):\n font = load_font(sz, title)\n lines = break_lines(title, font)\n if len(lines) > 3: continue\n if max(measure_line(font, l)[0] for l in lines) > MAX_TEXT_WIDTH: continue\n lh = int(sz * LEADING_FACTOR)\n total = lh * (len(lines) - 1) + font.getbbox(lines[-1])[3]\n if total > MAX_TEXT_HEIGHT: continue\n return font, lines, sz\n f = load_font(MIN_FONT_SIZE, title)\n return f, break_lines(title, f), MIN_FONT_SIZE\n\ndef composite_title(img, title):\n draw = ImageDraw.Draw(img)\n font, lines, sz = fit_title(title)\n lh = int(sz * LEADING_FACTOR)\n total = lh * (len(lines) - 1) + font.getbbox(lines[-1])[3]\n y = max(CANVAS - MARGIN - total, CANVAS // 2)\n rtl = detect_script(title) != \"latin\"\n for line in lines:\n x = CANVAS - MARGIN - measure_line(font, line)[0] if rtl else MARGIN\n draw.text((x, y), line, font=font, fill=(255, 255, 255))\n y += lh\n return img\n\ndef strong_overlay(img):\n ov = Image.new(\"RGBA\", img.size, (0, 0, 0, 0))\n d = ImageDraw.Draw(ov)\n start = int(CANVAS * 0.40)\n for y in range(start, CANVAS):\n d.line([(0, y), (CANVAS, y)], fill=(0, 0, 0, int((y - start) / (CANVAS - start) * 230)))\n return Image.alpha_composite(img.convert(\"RGBA\"), ov).convert(\"RGB\")\n```\n\n## QA checklist\n\nVerify: 1400x1400 JPG/PNG <1 MB, typography present with correct font/alignment/white/margins, overlay on user-provided only, no faces/text/logos in AI output. If any check fails, fall through to next path.\n\nFile v0.2.0:references/episode-description.md\n\n# Episode Description Format\n\nReference for building the HTML description that appears in the Spotify show-notes panel. Spotify auto-links `(M:SS)` timestamps for in-app seeking.\n\n## Format\n\nThe description uses HTML `

` tags with timestamped entries on a single line (no literal newlines in the final string):\n\n```html\n

Summary of today's episode themes in 1-2 sentences.

(0:00) - Introduction

(0:18) - First segment title - source

(1:42) - Second segment title - source

(4:30) - Sign-off

\n```\n\n## Build it from the timeline\n\nRead chapter entries from `timeline.json` (ignore image, link, and `spotify_entity` companions — those appear in the player, not the show notes):\n\n```python\nimport json\n\ntimeline = json.load(open('timeline.json'))\nchapters = [item['chapter'] for item in timeline['items'] if 'chapter' in item]\n# source_links maps chapter title -> original article URL (from sourcing phase)\nsource_links = {\"Segment title\": \"https://source.url/article\"}\n\nparts = ['

Summary of episode themes.

']\nfor ch in chapters:\n ms = ch['start_time_ms']\n ts = f\"({ms // 60000}:{(ms % 60000) // 1000:02d})\"\n title = ch['title']\n url = source_links.get(title)\n if url:\n parts.append(f\"

{ts} - {title} - source

\")\n else:\n parts.append(f\"

{ts} - {title}

\")\n\ndescription = ''.join(parts)\n```\n\n## Rules\n\n1. Every entry wrapped in its own `

...

` block\n2. Do NOT use `
` tags — they render as literal text on the Spotify desktop app\n3. Timestamps as plain text `(M:SS)` in parentheses — Spotify auto-links these for seeking. Do NOT wrap timestamps in `` tags\n4. No leading zero on minutes, always two-digit seconds: `(0:05)`, `(1:42)`, `(12:30)`\n5. External source links use HTML anchors: `source`\n6. Use single quotes inside `href` to avoid shell escaping issues\n7. Entire description must be a single line with NO literal newlines\n8. Start with a 1-2 sentence summary paragraph\n9. Use `-` (hyphen) not `—` (em dash) to avoid shell encoding issues\n10. Include Introduction and Sign-off entries (no source links for these)\n11. Every entry with a known source URL MUST include the link — never fabricate URLs\n12. ``, `` for emphasis (sparingly)\n\n## Naming (per Spotify guidelines)\n\n- **Show name:** Short, memorable, and searchable. Avoid generic names that get lost in search results\n- **Episode title:** Include the date or episode number for recurring shows. Keep under ~60 characters so it doesn't truncate in the app\n- **Description summary:** The first 1-2 sentences appear as a preview in podcast apps — front-load the most interesting hook, don't waste it on boilerplate\n\nFile v0.2.0:references/local-preview.md\n\n# Local Preview Pages\n\nLocal browser preview pages, served before anything is uploaded: the **finished episode** (a mini Spotify player) and the **voice sample** (a one-card player). Nothing leaves the machine — no uploads, no external requests. Use them from any flow — onboarding or the standard checklist.\n\n## Assets\n\nCreate a preview directory in the session temp dir: `preview//` containing `index.html`. Reference the episode MP3 and cover image in place — symlink them into the directory (`ln -s`, macOS/Linux) or serve the directory where they already live. On Windows, skip symlinks (they need elevated privileges): serve from where the assets live, or copy them. Do not copy multi-megabyte audio on other platforms just to preview it.\n\n## The page\n\n`index.html` is one self-contained file (inline CSS/JS, no CDN or external fetches) that mirrors the Spotify player look:\n\n- Dark theme (near-black `#121212` background, Spotify green `#1DB954` accent, white/grey text)\n- Two panes. Left: show name as a small uppercase eyebrow, episode title, duration, description, a thin timeline scrubber with a tick mark per chapter, then the full chapter list — each row an icon, chapter title, and `m:ss` start time from `timeline.json`. Right: the cover image (fallback: a green gradient placeholder with a music-note glyph).\n- A round play/pause button wired to an `