Artwork
Elements that provide artwork for tracks.
-
Audio Metadata
Extracts embedded artwork from audio files using the music-metadata library.
-
Input
Fetches artwork by delegating to the configured input element's artwork method.
-
Last.fm
Fetches cover art from the Last.fm API using track artist and album tags.
-
MusicBrainz
Fetches cover art from MusicBrainz and the Cover Art Archive using track artist and album tags.
Configurators
Intermediates in order to make a particular kind of element configurable. In other words, these allow for an element to be swapped out with another that takes the same set of the actions and data output.
-
Artwork
Takes artwork components as children and tries each in sequence, returning the first non-null result.
-
Collaboration
Holds collaboration sources as children. Each source declares the hint prefix it handles, so the cooperative-playlists orchestrator can resolve collaborators across protocols.
-
Input
Allows for multiple inputs to be used at once.
-
Metadata
Takes metadata components as children and chains their patches in sequence.
-
Output
Enables the user to configure a specific output. If no default output is set, it creates a temporary session by storing everything in memory.
-
Scrobbles
Configure multiple scrobblers (music trackers).
-
Upload
Takes upload components as children and enables configuring one or more upload destinations.
Engines
Elements with each a singular purpose. There are orchestrator elements that control these.
-
Audio
Plays audio through audio elements.
-
Queue
A queue for tracks.
-
Repeat & Shuffle
Signals synced with local storage (classified by group) that decide if audio should be repeated and if the queue should be shuffled when filling it.
-
Scope
Signals that could influence the scope of a set of tracks.
Input
Inputs are sources of audio tracks. Each track is an entry in the list of possible items to play. These can be files or streams, static or dynamic.
-
Dropbox
Dropbox, using the Dropbox v2 HTTP API.
-
Ephemeral Cache
Ephemeral blobs stored in indexedDB, resolving creates temporary Blob URLs. Not responsible for storing blobs.
-
Firkin
Firkin account files plus generic CID-addressed blobs. Generic blobs resolve anonymously via RASL by default; a read token in the URI opts into authenticated access.
-
HTTPS
HTTPS URLs to audio files or streams.
-
HTTPS + JSON
HTTPS servers with JSON directory listings.
-
Icecast
Icecast internet radio streams. Fetches ICY metadata to populate track information.
-
Local
Audio files or directories from your local device, using the browser's File System Access API.
-
Opensubsonic
(Open)subsonic audio servers.
-
S3
AWS S3 and services that provide the same surface API such as Cloudflare R2.
-
WebDAV
WebDAV servers. Depends on a service worker handling the
diffuse:basic-authquery parameter and converting it to aAuthorizationheader.
Metadata
Elements that provide metadata for tracks.
-
Audio File
Extracts tags and audio stats from audio files using the music-metadata library.
-
Spectrogram
Decodes a track's audio, computes a spectrogram and stores the derived spectral descriptors (centroid, rolloff, spread, flatness, flux) on the track's stats.
Orchestrators
These are element compositions, logic only. Mostly exist in order to construct sensible defaults.
-
Artwork
Fetches cover art for a given set of tracks, stored locally in indexedDB. Uses the artwork configurator to try each configured source in sequence.
-
Automatic Queue
Fill the queue automatically with non-manual items (shuffled or regular, based on repeat-shuffle engine).
-
Controller
Provides commonly used computed signals derived from the audio engine, queue engine, and output. Exposes currentTrack(), isPlaying(), and references to the underlying engines.
-
Cooperative Playlists
Exposes the cohesive view of playlists shared with collaborators. Reads collaboration records from the given output, resolves collaborators through registered collaboration sources, and provides merged
playlistItemsandplaylistssignals. An AT Protocol source is included. Collaborator items are never written back, so each account only edits its own items. -
Cover Groups
Groups tracks by cover art to form collections.
-
Favourites
Mark tracks as favourites. Automatically creates an unordered 'Favourites' playlist.
-
Media Session
Keeps the browser/os media session in sync with queue and audio state. Adds handlers for previous, next, seek to, etc.
-
Output
A default output configuration. Contains all the outputs provided here along with the relevant transformers.
-
Process Inputs Into Tracks
Whenever the cached tracks are initially loaded through the passed output element it will list tracks by using the passed input element. Afterwards it loops over all tracks and checks if metadata needs to be fetched. If anything has changed, it'll pass the results to the output element.
-
Queue + Audio
Connects the given queue engine to the given audio engine.
-
Scoped Tracks
Watches the given output's tracks collection and runs them through a built-in search index. Can perform a search and other ways to reduce the scope of tracks based on the given scope engine. Provides a tracks signal similar to output.tracks.collection.
-
Scrobble + Audio
Connects the audio engine with a scrobbler element. Calls nowPlaying when a track starts playing and scrobble once the user has listened long enough.
-
Sources
Monitor tracks from the given output to form a list of sources based on the input's sources return value.
-
Spectrogram + Audio
When a track starts playing and is missing spectrogram-derived stats, analyses it via the spectrogram metadata element and persists the result to the output. Only the leader tab performs the analysis.
Output
Output is application-derived data such as playlists. These elements can receive such data and keep it around. These are categorised by the type of data they ingest, or many types in the case of polymorphic. Optionally use transformers to convert output into the expected format.
-
Polymorphic / IndexedDB
Stores output into the local indexedDB. Supports any type of data that indexedDB supports.
-
Bytes / Dropbox
Store output data as raw bytes in the Dropbox app folder.
-
Raw / Firkin / Encrypted / Incremental Automerge
The complete Firkin userdata output: an append-only log of encrypted Automerge changes on a Firkin instance. Each save appends only the changes since the log last saw them (a whole document every 32 saves), entries are sealed per save, and per-device manifests are signed by the writer's session key.
-
Bytes / S3
Store output data on AWS S3 or compatible services such as Cloudflare R2.
-
Bytes / WNFS (Firkin)
Stores user data in a private WNFS on a Firkin instance, with all blocks held by the account. Playlist items and tracks are written as one file per bundle (per playlist or input source), so a save only rewrites the bundle that changed. Requires a passkey-backed Firkin account.
Supplements
Additional elements, such as scrobblers.
-
Publish on the Atmosphere
Publishes playlist items, facets and collaborations to the user's AT Protocol account beside whichever output is selected. Owns the shared AT Protocol publish session and only writes changed records.
-
Last.fm Scrobbler
Scrobbles track plays to Last.fm.
-
ListenBrainz Scrobbler
Scrobbles track plays to ListenBrainz.
-
Rocksky Scrobbler
Scrobbles track plays to Rocksky.
Transformers
Transform data from one format or schema into another. See the definitions section below for more information. Just as configurators, these are intermediates and require to have the same set of actions as the element it targets.
-
Output / Bundles
Exposes an output's collections as bundles: one per playlist, and one per track source (an S3 bucket, a Subsonic server, a directory, …). Without an input to name the source, tracks fall back to their URI scheme. Other collections pass through unchanged, and saving bundles flattens them back into the wrapped output.
-
Output / Bytes / DASL Sync
Syncs data between local and remote using CID-based diffing and performs union merges with tombstone tracking when both sides have diverged.
-
Output / Bytes / JSON
Raw data schema output to and from JSON Uint8Array.
-
Output / Refiner / Default
Removes output state that is not meant to be saved to storage, such as ephemeral tracks. Ideally part of every theme.
-
Output / Refiner / Initial Contents
Sets the initial contents for an output on first load.
-
Output / Refiner / Path Collections
Generates ephemeral playlists based on a path part of each track's URI. The 1-based part can be set using the
path-partattribute (defaults to the first). Percent-encoded parts are decoded. Items with an id prefixedpath-collections/are excluded from storage. -
Output / String / JSON
Raw data schema output to and from JSON UTF8 string.
Upload
These elements are paired with input elements, extending their functionality. The upload element uploads or removes audio files, and the input element then lists them.
-
Dropbox
Uploads and deletes files on Dropbox using the Dropbox v2 HTTP API.
-
Firkin
Uploads files to Firkin and records them in the account's file registry.
-
S3
Uploads and deletes files in an S3-compatible bucket using the S3 HTTP API. Buckets are connected on the S3 connect page.
-
WebDAV
Uploads and deletes files on a WebDAV server using PUT and DELETE requests.
Definitions
All of the elements here are built with these data definitions in mind. That said, you can mix elements that use different definitions; you just have to put a transformer between them in order to translate between them, if needed.
-
Output / Collaboration
Represents a collaboration between multiple collaborators on a subject, such as a playlist.
-
Output / Facet
A MASL manifest (
resources+blocks), or a pointer (uri) to an.htmlfile or.tileCAR. -
Output / Playlist Item
Represents a single item in a playlist. Tracks are matched based on the given criteria. A playlist is formed by grouping items by their playlist property.
-
Output / Playlist Item Bundle
A bundle of playlist items.
-
Output / Setting
Represents a single application setting as a key-value pair.
-
Output / Track
Represents audio that can be played, or a placeholder for a source of tracks. Contains a URI that will resolve to the audio.
-
Output / Track Bundle
A bundle of tracks.