Diffuse

Elements

Diffuse was built using these web components, consume these using the create tool, the Javascript package, or the linked Javascript files down below.

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

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.
  • HTTPS
    HTTPS URLs to audio files or streams.
  • 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-auth query parameter and converting it to a Authorization header.

Metadata

Elements that provide metadata for tracks.

  • Audio File
    Extracts tags and audio stats from audio files using the music-metadata library.

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.
  • 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.
  • Path Collections
    Wraps an output element to generate ephemeral playlists based on the first path segment of each track's URI. Ephemeral items are excluded from storage.
  • 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.

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 / S3
    Store output data on AWS S3 or compatible services such as Cloudflare R2.
  • Raw / AT Protocol
    Store your user data on the storage associated with your ATProtocol identity. Data is lexicon shaped by default so this element takes in that data directly without any transformations.

Supplements

Additional elements, such as scrobblers.

  • Last.fm Scrobbler
    Scrobbles track plays to Last.fm.
  • [todo] ListenBrainz Scrobbler
    Scrobbles track plays to ListenBrainz.
  • [todo] 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.

  • [todo] Output / Bytes / Automerge
    Translate data to and from an Automerge CRDT.
  • 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 / Raw / AT Protocol Sync
    Wraps an AT Protocol output with a local IndexedDB cache. Uses the repo revision to skip unnecessary fetches and performs union merges with tombstone tracking when both local and remote have diverged.
  • 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 / Track URI Passkey
    Encrypts track URIs using a passkey-derived PRF key. On read, decrypts encrypted:// URIs transparently; on write, re-encrypts all URIs before passing downstream.
  • Output / String / JSON
    Raw data schema output to and from JSON UTF8 string.

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.