Spotify in your terminal. Spotify data in your Python app.
A typed, async Python library for Spotify's public catalogue, playlists, and connected players.
No developer app or API key for public data.
Get started · Explore · Python API · Documentation · Sponsor
Language: English · Português (Brasil) · Español · Français
Connect · Search, navigate and control an existing Spotify player from your terminal. Spotify plays the audio; SpotAPI sends the controls.
Python 3.11+ is required. Start with a real search—no Spotify login, Client ID or configuration needed.
python -m pip install spotapi
python -m spotapi search "Daft Punk"That's the public catalogue. Search, resolve Spotify links, inspect credits and read public playlist metadata without setting up a Spotify developer application. The first request can take longer while SpotAPI discovers the current web-player queries; subsequent requests reuse the cached results.
Building with Python instead? The same installation provides a typed API. No terminal interface is required:
import asyncio
from spotapi import Public
async def main():
results = await Public.search("Daft Punk", limit=5)
for track in results.tracks:
print(track.name, track.uri)
asyncio.run(main())More Python examples · Playlist audit and CSV export
Want something you can browse? Open the interactive terminal explorer:
python -m pip install "spotapi[demo]"
python -m spotapi discover "Daft Punk"Navigate search results, artwork and Spotify links without signing in. Discover example · Troubleshooting
The CLI goes beyond search. Inspect an artist, pull track credits, or list a public playlist:
python -m spotapi search "Daft Punk" --type artist --json
python -m spotapi get SPOTIFY_URL
python -m spotapi playlist items PLAYLIST_ID --limit 10These work without a developer API key. Account operations—liked music, private playlists and control of your existing Spotify player—require your own Spotify session. See the account guide and player guide.
Connect brings searching, device selection, up-next, playback and a live activity log into one keyboard-friendly terminal session. It operates an existing signed-in Spotify player; it does not stream, download or decrypt tracks.
Launch Connect with the optional terminal interface:
python -m pip install "spotapi[connect]"
python -m spotapi connectIf pip warns that the connect extra does not exist, that PyPI release predates the extra. Until the next release, clone the repository and run python -m pip install -e ".[connect]" from its root.
Use search Daft Punk to find music, queue 1 to add a result, or pause, next, and seek 1:30 to control playback. Open /devices to browse available players; /use 2 selects one without transferring playback, while /transfer 2 transfers playback. Ctrl+P opens the command palette.
Connect requires your Spotify session for player controls. For browser-based sign-in, you may also need the browser extra and Playwright's Chromium installation; see the Connect guide for setup.
SpotAPI also powers Studio, a desktop music explorer built on the same library. Open tracks, inspect credits, follow artists and albums, and display timed lyrics. With a connected Spotify player, clicking a lyric can seek playback to that line.
Watch the synchronized-lyrics demo (GIF, about 11 MB) · Studio itself does not stream full Spotify tracks.
python -m pip install "spotapi[studio]"
python -m spotapi studioStudio uses a native WebView. Studio setup explains platform requirements and Spotify sign-in. Lyric availability depends on the source and account entitlements; seeking needs an authenticated, controllable player.
The terminal demos are examples. SpotAPI is a Python library first: async operations, typed results, explicit network calls and reusable sessions.
import asyncio
from spotapi import Public
async def main() -> None:
results = await Public.search("Daft Punk", limit=5)
for track in results.tracks:
print(track.name, track.uri)
asyncio.run(main())For several related operations, reuse one catalogue session:
import asyncio
from spotapi import Catalogue
async def main() -> None:
async with Catalogue() as spotify:
results = await spotify.search("Daft Punk")
if results.artists:
artist = await spotify.get_artist(results.artists[0].uri)
print(artist.name)
asyncio.run(main())Working with large playlists? Audit up to 10,000 playlist occurrences, identify duplicate tracks and unavailable entries, and export a CSV. The example pages through results instead of loading the whole playlist into memory. Run it from a repository checkout.
| Build | Start here |
|---|---|
| Music search or public metadata tools | Public catalogue |
| A playlist organizer that handles duplicate tracks correctly | Playlist API |
| A live now-playing display or controller | Player example |
| A personal music dashboard | Account and statistics |
| A DJ crate using tempo and harmonic keys | Playlist crate |
| An experimental local music recommender | Taste Lab |
- Start without credentials. Public catalogue search and metadata require no Spotify developer app.
- Typed, async results. Work with Python models instead of guessing dictionary keys.
- Explicit I/O. Reading a model doesn't silently trigger another HTTP request.
- More than read-only metadata. With your authenticated session, manage saved music, edit playlist occurrences and control existing players.
- Designed for exploration. Use the CLI, Discover and Studio to understand capabilities before integrating them into code.
SpotAPI uses unofficial Spotify web-player endpoints, so behavior can change when Spotify changes those endpoints. It is not a substitute for the official Web API in every use case, and public-data access is different from authenticated playback access. Compare the APIs · Verification boundaries
Quickstart · API reference · Coming from Spotipy · CLI and discovery · Troubleshooting
Upgrading from v1? SpotAPI 2 is async-first and contains breaking changes. Existing v1 apps can pin spotapi==1.2.8 while migrating, or use SyncCatalogue for new synchronous scripts. Read the migration guide.
SpotAPI is free and open source. Sponsorship helps fund maintenance, testing and documentation without changing the library's behavior or adding paywalls.
Build developer tools? Explore sponsorship options to reach developers using SpotAPI. Paid placements are clearly labeled and help support the project.
Bug reports, reproducible issues and thoughtful contributions are welcome. Contributing · Tests · Legal notice · GPL-3.0
If SpotAPI helps you build something, star the repository to help other developers discover it.

