Official Elixir SDK for Rocksky.
A thin wrapper over the :rocksky_erl Rustler NIF (the shared Rust core,
rocksky-sdk): AppView reads, AT Protocol PDS writes (scrobble fan-out, like,
follow, shout) and the identity hashes — the same engine behind every Rocksky
SDK.
Reads/writes return {:ok, value} | {:error, message} with binary-keyed
maps (the wire shape). Records passed to the write verbs are maps with
camelCase binary keys — "title", "artist", "album", "albumArtist",
"durationMs", …
{:ok, stats} = Rocksky.global_stats()
Rocksky.song_hash("Chaser", "Calibro 35", "Jazzploitation")Summary
Functions
Albums catalog (app.rocksky.album.getAlbums) — see catalog_songs/5.
Artists catalog (app.rocksky.artist.getArtists) — see catalog_songs/5.
Songs catalog (app.rocksky.song.getSongs) with optional genre and RSQL
filter — a Rocksky.Filter or a raw RSQL binary.
Delete an equalizer preset by rkey (token required). Returns true.
Saved equalizer presets (app.rocksky.equalizer.listPresets). An empty
actor lists the token holder's own presets (token required); a handle or
DID is a public read (no token needed).
Follow an account by DID.
Universal read escape hatch — call any app.rocksky.* query by nsid.
Platform-wide totals.
Keep the local dedup index hydrated from Jetstream in the background.
Like a record by strong reference.
Log in with an app password, persisting the session at session_path.
Returns an opaque agent handle (a NIF resource freed by GC).
Resolve full canonical metadata for a bare title + artist (matchSong).
album steers the match toward that release (case-insensitive) so a
remaster/live/single edition doesn't shadow the intended album.
The authenticated viewer's notifications, most recent first (token required).
params may include "limit" (default 30) and "cursor".
An actor's detailed profile.
Create or update an equalizer preset (token required). input is a map with
camelCase string keys: required "name" and "bands" ([%{"frequency" => _, "gain" => _, "q" => _}]); optional "precut" (-240..0). The rkey is the
slugified name, so re-saving a name overwrites. Returns the saved preset.
Proactively refresh the session (keep-alive).
Reply to a shout with an optional GIF/sticker/clip (see shout_with_gif/5).
Scrobble a play (fans out to artist/album/song/scrobble). Returns the URIs.
Scrobble feed (app.rocksky.scrobble.getScrobbles) — the whole platform, one
actor (did), or the accounts an actor follows (did + following: true).
filter is a Rocksky.Filter (dotted selectors like :"track.artist" reach
the joined track/user/artist) or a raw RSQL binary.
Scrobble from just a title + artist (album optional): resolve full metadata
via matchSong, then fan out. input is a map with camelCase string keys:
required "title"/"artist"; optional "album", "mbId", "isrc" (match
anchors) and "timestamp" (scrobbled-at Unix seconds, default now).
An actor's scrobbles, newest first.
Post a shout on a subject.
Post a shout with an optional GIF/sticker/clip. Pass at least one of message
/ gif. gif is a map ("url" required, plus "previewUrl", "alt",
"width", "height") or nil.
Identity hash of a song — identical across every Rocksky SDK.
Download the caller's repo and (re)build the local dedup index (needs a dedup_path at login).
Top artists chart over a typed date window (see top_tracks_interval/4).
Platform-wide top tracks chart.
Top tracks chart over a typed date window.
The authenticated viewer's unread-notification count (token required).
Returns %{"count" => n}.
Mark notifications as viewed (token required). ids is a list of notification
ids, or [] to mark all. Returns %{"unreadCount" => n}.
Functions
Albums catalog (app.rocksky.album.getAlbums) — see catalog_songs/5.
Artists catalog (app.rocksky.artist.getArtists) — see catalog_songs/5.
Songs catalog (app.rocksky.song.getSongs) with optional genre and RSQL
filter — a Rocksky.Filter or a raw RSQL binary.
Rocksky.catalog_songs(50, 0, nil, Rocksky.Filter.eq(:artist, "Daft Punk"))Delete an equalizer preset by rkey (token required). Returns true.
Saved equalizer presets (app.rocksky.equalizer.listPresets). An empty
actor lists the token holder's own presets (token required); a handle or
DID is a public read (no token needed).
Follow an account by DID.
Universal read escape hatch — call any app.rocksky.* query by nsid.
params is a map of string params; the whole read-query catalog is reachable.
Rocksky.get("app.rocksky.album.getAlbum", %{"uri" => uri})
Rocksky.get("app.rocksky.charts.getScrobblesChart", %{"did" => did})Platform-wide totals.
Keep the local dedup index hydrated from Jetstream in the background.
Like a record by strong reference.
Log in with an app password, persisting the session at session_path.
Returns an opaque agent handle (a NIF resource freed by GC).
Resolve full canonical metadata for a bare title + artist (matchSong).
album steers the match toward that release (case-insensitive) so a
remaster/live/single edition doesn't shadow the intended album.
The authenticated viewer's notifications, most recent first (token required).
params may include "limit" (default 30) and "cursor".
An actor's detailed profile.
Create or update an equalizer preset (token required). input is a map with
camelCase string keys: required "name" and "bands" ([%{"frequency" => _, "gain" => _, "q" => _}]); optional "precut" (-240..0). The rkey is the
slugified name, so re-saving a name overwrites. Returns the saved preset.
Proactively refresh the session (keep-alive).
Reply to a shout with an optional GIF/sticker/clip (see shout_with_gif/5).
Scrobble a play (fans out to artist/album/song/scrobble). Returns the URIs.
Scrobble feed (app.rocksky.scrobble.getScrobbles) — the whole platform, one
actor (did), or the accounts an actor follows (did + following: true).
filter is a Rocksky.Filter (dotted selectors like :"track.artist" reach
the joined track/user/artist) or a raw RSQL binary.
Rocksky.scrobble_feed(nil, false, 50, 0, Rocksky.Filter.eq(:"track.artist", "Daft Punk"))Scrobble from just a title + artist (album optional): resolve full metadata
via matchSong, then fan out. input is a map with camelCase string keys:
required "title"/"artist"; optional "album", "mbId", "isrc" (match
anchors) and "timestamp" (scrobbled-at Unix seconds, default now).
Rocksky.scrobble_match(agent, %{"title" => "Chaser", "artist" => "Calibro 35"})An actor's scrobbles, newest first.
Post a shout on a subject.
Post a shout with an optional GIF/sticker/clip. Pass at least one of message
/ gif. gif is a map ("url" required, plus "previewUrl", "alt",
"width", "height") or nil.
Identity hash of a song — identical across every Rocksky SDK.
Download the caller's repo and (re)build the local dedup index (needs a dedup_path at login).
Top artists chart over a typed date window (see top_tracks_interval/4).
Platform-wide top tracks chart.
Top tracks chart over a typed date window.
interval is :all | {:days, n} | {:weeks, n} | {:months, n} |
{:years, n} | {:range, start_rfc3339, end_rfc3339}.
Rocksky.top_tracks_interval(10, 0, {:days, 7})The authenticated viewer's unread-notification count (token required).
Returns %{"count" => n}.
Mark notifications as viewed (token required). ids is a list of notification
ids, or [] to mark all. Returns %{"unreadCount" => n}.