zzstoatzz.io
audio streaming app
plyr.fm
1---
2title: "for developers"
3description: "build on plyr.fm — API, lexicons, and architecture"
4---
5
6plyr.fm exposes a public API, a Python SDK, and an MCP server. build players, analytics, recommendation engines, or integrations on top of the open data.
7
8## API
9
10the full OpenAPI spec is at [api.plyr.fm/docs](https://api.plyr.fm/docs). key endpoints:
11
12| endpoint | description |
13|----------|-------------|
14| `GET /search/` | search tracks, artists, playlists |
15| `GET /tracks/{id}` | get track metadata |
16| `GET /tracks/{id}/stream` | stream audio |
17| `GET /stats` | platform stats |
18| `GET /oembed` | oEmbed endpoint |
19
20authenticated endpoints require a developer token from [plyr.fm/portal](https://plyr.fm/portal).
21
22## Python SDK
23
24```bash
25uv add plyrfm
26```
27
28```python
29from plyrfm import PlyrClient
30
31client = PlyrClient()
32
33# list tracks
34for track in client.list_tracks(limit=5):
35 print(f"{track.id}: {track.title} by {track.artist}")
36
37# get a specific track
38track = client.get_track(42)
39```
40
41authenticated operations (upload, download, manage your tracks) require a token:
42
43```python
44client = PlyrClient(token="your_token")
45my_tracks = client.my_tracks()
46client.upload("song.mp3", "My Song")
47```
48
49see the [plyr-python-client repo](https://github.com/zzstoatzz/plyr-python-client) for full docs.
50
51## MCP server
52
53the `plyrfm-mcp` package provides an MCP server for AI assistants:
54
55```bash
56uv add plyrfm-mcp
57```
58
59add to Claude Code:
60
61```bash
62claude mcp add plyr-fm -- uvx plyrfm-mcp
63```
64
65tools include `search`, `list_tracks`, `top_tracks`, `tracks_by_tag`, and more. see the [repo](https://github.com/zzstoatzz/plyr-python-client) for setup options.
66
67## developer tokens
68
69generate tokens at [plyr.fm/portal](https://plyr.fm/portal). tokens are scoped to your account and can be revoked at any time.
70
71## ATProto lexicons
72
73all plyr.fm data uses custom ATProto lexicons under the `fm.plyr` namespace. see the [lexicons overview](/lexicons/overview/) for schemas and record types.
74
75## contributing
76
77plyr.fm is open source. see the [contributing guide](/contributing/) to get involved.