Diffuse

Elements

Diffuse was built using these web components, consume these using the build 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.
  • 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.

  • HTTPS
    HTTPS URLs to audio files or streams.
  • [todo] HTTPS (JSON)
    Generate tracks based on HTTPS servers that provide 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
    Add any (open)subsonic server.
  • S3
    AWS S3 and services that provide the same surface API such as Cloudflare R2.
  • [todo] WebDAV
    Add any WebDAV server.

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.

  • Automatic Queue
    Fill the queue automatically with non-manual items (shuffled or regular, based on repeat-shuffle engine).
  • Favourites
    Mark tracks as favourites. Automatically creates an unordered 'Favourites' playlist.
  • Input
    A default input configuration. Contains all the inputs provided here.
  • Media Session
    Keeps the browser/os media session in sync with queue and audio state. Adds handlers for previous, next, seek to, etc.
  • Offline
    Registers a service worker that makes the page available offline. Resources (except audio & video) are cached as they load and served from cache when offline.
  • 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.
  • 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.
  • 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.
  • 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

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
  • [todo] ListenBrainz Scrobbler
  • [todo] Rocksky Scrobbler
  • [todo] Teal.fm Scrobbler

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.
  • [todo] Output / Bytes / Cambria Lenses
    Uses the Cambria library to seamlessly translate between data schemas so that no data migration is needed.
  • 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 ⇄ 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
    The task of a refiner transformer is to remove the output state that is not meant to be saved to storage. For example, ephemeral tracks; this transformer will keep them in memory, but they will not be present in the output. Ideally this is part of every theme, but you may swap it out with another transformer that might provide better defaults.
  • 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. Tracks that cannot be decrypted are held separately and excluded from the visible collection.
  • Output / String / JSON
    Raw data schema output ⇄ 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.