AutoGineer
Generated banner for Save To Spotify
Generated logo for Save To Spotify

Save To Spotify

ClineOfficialPublished by Cline

  • Skill
  • Workflow
  • Automation and integrations
  • Apache-2.0
  • Medium risk
Download ZIP

From the author

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.
— the description by Cline

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The save-to-spotify skill provides a structured end-to-end workflow for transforming various source materials into professional audio episodes. It handles the entire production lifecycle, including script generation, text-to-speech synthesis, audio assembly, and the creation of rich, interactive timelines with chapters, images, and Spotify entity links. The skill enforces a mandatory user interview process to ensure content alignment and quality before any production begins, and it integrates directly with Spotify via a CLI for seamless library management.

What it does

  • Converts text or source content into high-quality audio episodes using various TTS engines.
  • Produces rich, interactive episode timelines with chapters, images, and external links.
  • Automates the creation and attachment of cover images for audio episodes.
  • Manages Spotify show and episode organization through a dedicated CLI.
  • Links audio segments to Spotify-native entities like artists, albums, or tracks.
  • Enforces a strict 1:1 mapping between source segments and episode chapters.

When to use it

  • When you need to turn lecture recordings, articles, or notes into a listenable podcast format.
  • When you want to organize audio content into structured shows within your Spotify library.
  • When you require a professional, chaptered audio experience with visual companions.
  • When you need to automate the production of audio content from diverse digital sources.

Advantages

  • Ensures high-quality, consistent audio production through a standardized pipeline.
  • Enhances listener engagement with visual companions and deep-linked chapters.
  • Provides flexible TTS options to match the desired tone and language.
  • Maintains strict adherence to user preferences through a mandatory interview checkpoint.
  • Supports complex content like bilingual or multi-voice segments.

Usage examples

“I have a series of articles about space exploration. Can you turn them into a podcast episode?”
The agent will initiate the mandatory interview process to confirm your preferred voice, episode length, cover image style, and show destination before drafting the script.
“Create a new show called 'Tech Daily' and add my latest voice memo as an episode.”
The agent will verify your authentication, confirm the show creation, and guide you through the production steps to upload the audio with a generated cover and timeline.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/cline/save-to-spotify/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip save-to-spotify.zip -d .agents/skills

Documentation by Cline

Audio Content Production Skill

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.

Shows are folders for organizing saves.

You 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.

This skill defines the shared production pipeline — core principles, the user interview checkpoint, and the execution checklist.

Reference Directory

These files cover the detailed rules. Load the one you need — don't inline them.

  • references/cli-usage.md — Binary install, auth, upload/shows/episodes/timeline commands, JSON mode, error handling, troubleshooting, and common end-to-end workflows

  • 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

  • references/audio-providers.md — TTS engine selection, voice config, ffmpeg assembly, silence generation, timeline timestamp calculation

  • references/cover-image.md — Cover image paths (user-provided, AI-generated, CDN artwork), typography rules, font & RTL, Pillow compositing recipe

  • references/timeline.md — Timeline data model, validation rules, companion images (sourced / AI-generated / mixed / skip), including DALL-E / Stable Diffusion code and batch generation

  • references/episode-description.md — HTML description format, Python builder from timeline.json, formatting rules

  • references/content-quality.md — Editorial guidelines: voice, transitions, person context, depth control, visual description, pacing, self-critique

Install

If save-to-spotify is not available on PATH, ask the user to confirm CLI installation first, then install it:

curl -fsSL https://saveto.spotify.com/install.sh | bash

See references/cli-usage.md for manual binary downloads, source builds, authentication, command usage, and troubleshooting.

Core Principles

Read-only. Always.

When 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.

Be the listener's eyes

Podcast 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.

Deep-link everything

Every 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.

Respect Third-Party Rights

The 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.

Prefer Spotify-native references

When 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.

Segment-to-source integrity

The 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.

Save incrementally

Write collected data to disk after each sourcing step. If a later step fails, previous work is preserved.

Pacing and silence

Don'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.

User Interview (MANDATORY)

Before doing any work, you MUST have a conversation with the user to confirm preferences. Do not assume defaults. Ask, then STOP and wait for their reply. Do not proceed until they respond. Skipping the interview will feel efficient; don't. Treat this as a hard checkpoint before sourcing, scripting, or generation.

At minimum, always confirm these before producing anything:

  1. Content scope — What sources, topics, or material to use

  2. Language — What language the episode should be in (do not assume from the source language)

  3. Length — How long the episode should be

  4. TTS voice — Which voice to use (offer options from references/audio-providers.md)

  5. Cover image style — How to generate the cover image. Present these options (see references/cover-image.md for full details):

    • User-provided — the user supplies their own image file

    • AI-generated (default when image tools available) — unique image themed to the episode content, text composited with Pillow

    • CDN artwork (terminal fallback) — pre-designed abstract illustration from the STS CDN with Pillow typography. Always available

  6. Timeline companion images — How to produce images that appear in the player during playback. Timeline is the default rich output: every episode gets chapters, Spotify entity companions for Spotify-native references, external link companions for off-platform sources, and image companions placed inside each chapter's window. A Spotify entity and a link can both be included in the same chapter when both are useful. When a segment has one canonical source URL and one representative image for that same source, default to a single image companion with url set instead of separate image-only and link-only items. For images, present these options:

    • AI-generated — DALL-E, Stable Diffusion, or the user's preferred image model, from a themed prompt per segment. Best when sources lack usable imagery (meditation, fiction, study, abstract topics) or when the user wants a consistent visual style

    • Mixed (recommended default) — sourced where a natural image is available, AI-generated fill for segments that lack one. Aim for at least one image per chapter

    • Skip — chapters and link companions only, no images. Lightest pipeline, still richer than the old chapters-only output

  7. Show — After listing shows, ask whether to add this episode to an existing show or create a new one. Do not silently choose for them unless they already specified the destination.

Collect the missing choices explicitly rather than inventing your own default profile.

Ask these questions in your first response and STOP. Wait for the user to answer. Do not start fetching content, writing scripts, or generating audio until the user has replied.

If the user's initial prompt already covers some of these (e.g., "make an 8-minute English podcast about..."), skip those questions but still present a plan and wait for confirmation.

Plan confirmation

Before starting production, present a short plan:

  • Episode title, language, estimated length, number of segments, voice, show name

Say: "Here's what I'll produce — let me know if you'd like to change anything, or say 'go' to proceed."

Do not start production until the user confirms.

Execution Checklist

Every episode — regardless of content type — must complete these steps.

  1. Preflight install and auth — Run save-to-spotify --json auth status before any sourcing. 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 auth status again. If unauthenticated or token refresh is broken, prompt the user to save-to-spotify auth login first.

  2. Interview — Ask the user about preferences, including companion-image source. Present a plan and wait for confirmation

  3. Script — Write the script following this skill's universal rules (see references/content-quality.md)

  4. Critique — Self-review the script, revise without reordering or removing segments

  5. Produce — Generate audio per-segment, concatenate, convert to MP3 (see 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

  6. Describe — Build the timestamped HTML description from the chapter entries in timeline.json and source URLs (see references/episode-description.md)

  7. Cover image — Generate or select cover image (square, max 1 MB). MANDATORY — never skip this step (see references/cover-image.md)

  8. Save — Save MP3 with title, description, and cover image via save-to-spotify --json upload (see references/cli-usage.md)

  9. Timeline — Push timeline.json with timeline set (uploads image files automatically)

  10. Verify — Poll episodes status until READY

Files

references/cli-usage.md

Save to Spotify

CLI Usage

Reference for the save-to-spotify binary: installation, authentication, commands, flags, JSON mode, error handling, and common agent workflows.

Installation

One-line install (recommended)
curl -fsSL https://saveto.spotify.com/install.sh | bash

Detects 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).

Pin a version or change the install directory:

# Specific version
curl -fsSL https://saveto.spotify.com/install.sh | bash -s -- --version 0.1.1

# Custom directory
curl -fsSL https://saveto.spotify.com/install.sh | bash -s -- --dir ~/.local/bin

# Via environment variables
SAVE_TO_SPOTIFY_VERSION=0.1.1 SAVE_TO_SPOTIFY_INSTALL_DIR=~/.local/bin \
  curl -fsSL https://saveto.spotify.com/install.sh | bash
Download a binary manually

Grab the latest release for the platform from releases:

# macOS Apple Silicon
gh release download --repo spotify/save-to-spotify --pattern "save-to-spotify-darwin-arm64"
chmod +x save-to-spotify-darwin-arm64
sudo mv save-to-spotify-darwin-arm64 /usr/local/bin/save-to-spotify

# macOS Intel
gh release download --repo spotify/save-to-spotify --pattern "save-to-spotify-darwin-amd64"
chmod +x save-to-spotify-darwin-amd64
sudo mv save-to-spotify-darwin-amd64 /usr/local/bin/save-to-spotify

# Linux x86_64
gh release download --repo spotify/save-to-spotify --pattern "save-to-spotify-linux-amd64"
chmod +x save-to-spotify-linux-amd64
sudo mv save-to-spotify-linux-amd64 /usr/local/bin/save-to-spotify
Build from source

Requires Go 1.21+.

git clone https://github.com/spotify/save-to-spotify.git && cd save-to-spotify
go build -ldflags "-X github.com/spotify/save-to-spotify/cmd.commit=$(git rev-parse --short HEAD)" \
  -o save-to-spotify .
sudo mv save-to-spotify /usr/local/bin/

Verify installation:

save-to-spotify version

Authentication

The user must authenticate once before any save. The CLI uses OAuth 2.0 with PKCE -- no client secret needed.

Interactive (user has a browser)
save-to-spotify auth login

This opens the browser, the user approves, and a token is saved to ~/.config/save-to-spotify/token.json.

Headless (remote server, CI, or agent environment)
save-to-spotify auth login --no-browser

This 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.

Environment token (skip OAuth entirely)

If the user already has a Spotify access token (e.g. from another tool or CI secret):

export SAVE_TO_SPOTIFY_AUTH_TOKEN="BQD..."

When 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.

Check auth status
save-to-spotify --json auth status

Returns {"authenticated": true, "token_valid": true, ...} or {"authenticated": false}.

Token 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.

Print the access token
save-to-spotify token

Prints 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.

See spotify-api.md for the official developer.spotify.com references, OpenAPI spec URL, endpoint patterns, and URI-resolution helpers.

Saving media

Quick save (recommended for most cases)

The upload command is the simplest path -- one command to create an episode and save the file:

save-to-spotify --json upload recording.mp3 \
  --title "My Recording" \
  --summary "Description here" \
  --image cover.jpg

Output:

{"episode_uri": "spotify:episode:abc123", "title": "My Recording", "status": "PROCESSING"}

If the user has no shows yet, one is auto-created as "My Podcast".

Save to a specific show
save-to-spotify --json upload lecture.m4a \
  --title "Lecture 3: Distributed Systems" \
  --summary "CS 307 Spring 2024" \
  --show-id spotify:show:xyz789 \
  --image cover.jpg

When --show-id is omitted, the CLI uses the most recently created show.

Create a new show and save in one step
save-to-spotify --json upload keynote.mp3 \
  --title "2024 Keynote" \
  --summary "Opening talk by <speaker>" \
  --new-show "Conference Talks" \
  --image cover.jpg

--new-show and --show-id are mutually exclusive.

Granular episode creation

For more control, use episodes create instead of upload:

save-to-spotify --json episodes create \
  --title "Episode Title" \
  --file audio.mp3 \
  --summary "Episode description" \
  --show-id spotify:show:xyz789 \
  --image episode-cover.jpg \
  --language en

The difference: episodes create requires --summary and --file as explicit flags (not positional), and does not support --new-show.

Supported file formats

ExtensionTypeMIME
.mp3Audioaudio/mpeg
.m4aAudioaudio/mp4
.wavAudioaudio/wav
.oggAudioaudio/ogg

Maximum file size: 1 GB.

Managing shows

Shows are folders that group episodes. Every episode belongs to exactly one show.

# List all shows
save-to-spotify --json shows

# Create a show (always include --image)
save-to-spotify --json shows create --title "My Lectures" --summary "University recordings" --image cover.jpg

# Get show details
save-to-spotify --json shows get <show_id>

# Delete a show (and all its episodes)
save-to-spotify --json shows delete <show_id>

save-to-spotify --json shows should be the first show-management command you run. Check what already exists before creating a new show.

Managing episodes

# List episodes in a show
save-to-spotify --json episodes --show-id <show_id>

# Check episode readiness
save-to-spotify --json episodes status <episode_id>

# Delete an episode
save-to-spotify --json episodes delete <episode_id>

Show and episode metadata is immutable after creation. To change a title or description, delete and re-create.

Episode readiness

After saving, poll for readiness before sharing:

save-to-spotify --json episodes status <EPISODE_ID>

Output:

{"episode_uri": "spotify:episode:abc123", "readiness": "READY"}

Readiness values:

  • READY -- playable on Spotify

  • PROCESSING -- still being processed (wait and retry)

  • FAILED -- processing failed; check the episode metadata and re-save if needed

Most episodes are ready within 1-2 minutes. For large files, allow up to 5 minutes.

IDs and URIs

The CLI accepts both bare IDs and full Spotify URIs interchangeably, but agents should prefer the full Spotify URI form whenever possible:

  • abc123def456 (bare ID)

  • spotify:show:abc123def456 (full URI)

JSON output always includes the full URI form.

JSON mode

Always use --json when operating as an agent. It must appear before the command:

save-to-spotify --json <command> [flags]

In JSON mode:

  • All output is valid JSON on stdout

  • Errors are {"error": "message"} on stdout with exit code 1

  • Progress bars and activity indicators are suppressed

  • Informational messages to stderr are suppressed

Without --json, output is human-readable text.

Timeout control

The 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:

save-to-spotify --json --timeout 2m upload large-recording.mp3 --title "Long Episode" --image cover.jpg

Or via environment variable:

export SAVE_TO_SPOTIFY_TIMEOUT=2m

Common agent workflows

Create a rich-timeline episode end-to-end
# 1. Generate cover image (MANDATORY — see cover-image.md)
python3 generate_cover.py

# 2. Save with cover image
RESULT=$(save-to-spotify --json upload episode.mp3 \
  --title "Daily Digest - April 15, 2026" \
  --summary "$(cat description.txt)" \
  --image cover.jpg)
EP_URI=$(echo "$RESULT" | jq -r .episode_uri)
EP_ID=${EP_URI#spotify:episode:}

# 3. Set timeline (chapters + image/link/Spotify companions in one call)
save-to-spotify --json timeline set --episode-id "$EP_ID" --from-file timeline.json

# 4. Poll until ready
while true; do
  STATUS=$(save-to-spotify --json episodes status "$EP_ID" | jq -r .readiness)
  [ "$STATUS" = "READY" ] && break
  [ "$STATUS" = "FAILED" ] && echo "Processing failed" && exit 1
  sleep 15
done

echo "Episode ready: $EP_URI"
Save a single file
URI=$(save-to-spotify --json upload recording.mp3 --title "My Recording" --summary "A recording" --image cover.jpg | jq -r .episode_uri)
EP_ID=${URI#spotify:episode:}

while true; do
  STATUS=$(save-to-spotify --json episodes status "$EP_ID" | jq -r .readiness)
  [ "$STATUS" = "READY" ] && break
  [ "$STATUS" = "FAILED" ] && echo "Processing failed" && exit 1
  sleep 15
done
Batch save multiple files to one show
SHOW_URI=$(save-to-spotify --json shows create --title "Conference Talks 2024" --image show-cover.jpg | jq -r .show_uri)

for f in talks/*.mp3; do
  TITLE=$(basename "$f" .mp3 | tr '-' ' ')
  save-to-spotify --json upload "$f" --title "$TITLE" --summary "Conference talk" --show-id "$SHOW_URI" --image cover.jpg
done

Error handling

With --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.

RESULT=$(save-to-spotify --json upload episode.mp3 --title "My Episode" --image cover.jpg)
if echo "$RESULT" | jq -e .error > /dev/null 2>&1; then
  echo "Failed: $(echo "$RESULT" | jq -r .error)"
  exit 1
fi
EP_URI=$(echo "$RESULT" | jq -r .episode_uri)
EP_ID=${EP_URI#spotify:episode:}

while true; do
  STATUS=$(save-to-spotify --json episodes status "$EP_ID")
  READINESS=$(echo "$STATUS" | jq -r .readiness)
  [ "$READINESS" = "READY" ] && break
  [ "$READINESS" = "FAILED" ] && echo "Processing failed" && exit 1
  sleep 15
done

Common errors:

ErrorCauseAction
not authenticatedNo token fileRun auth login
token refresh failedRefresh token revokedRun auth login again
unsupported file extensionWrong file typeConvert to a supported format
file too largeOver 1 GBCompress or split the file
image too largeOver 1 MBResize the image
API error (429)Rate limitedWait and retry after a delay
API error (401)Token expired mid-requestRetry (auto-refresh will kick in)
API error (403)Insufficient permissionsRe-authenticate with auth login
--new-show and --show-id are mutually exclusiveConflicting flagsUse one or the other

Troubleshooting

Episode not appearing after saving

Use episodes status <id> to check readiness. Processing can take a few minutes after the save completes.

Image upload fails

Images must be .jpg, .jpeg, or .png, max 1 MB, with valid magic bytes (actual JPEG/PNG content, not just a renamed file).

"unsupported file extension" error

Only .mp3, .m4a, .wav, and .ogg are supported. Convert other formats first (e.g., ffmpeg -i input.webm output.mp3).

Environment variables reference

VariablePurpose
SAVE_TO_SPOTIFY_AUTH_TOKENBearer token; skips OAuth entirely (no refresh, no expiry tracking)
SAVE_TO_SPOTIFY_BACKEND_URLOverride backend URL
SAVE_TO_SPOTIFY_TIMEOUTAPI timeout duration (e.g. 30s, 2m)

Content policy

  • No copyrighted music: Content that is classified as music by Spotify's moderation system will be taken down.

  • Moderation applies: Standard Spotify podcast moderation policies apply. Content that violates policies will be removed and the user will be notified via email.

  • 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.

  • 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.

  • 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.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs network access

Security

What our scanner noticed· Medium risk

  • Instructions that use the network
  • Downloads piped into a shell

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Cline
Publisher
Cline (Official)
Source
cline/skills · skills/save-to-spotify · commit 2637846
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Cline.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download save-to-spotify.zip