Diffuse

Diffuse is a collection of custom elements that make it possible to listen to audio from various sources on your devices and the web, and to create the ideal digital listening experience for you.

⚠️ Heavily experimental

Themes

Themes are compositions and provide a traditional browser web application way of using them. Each theme is unique, not just a skin (ie. not like winamp skins).

For example, most themes here will limit the currently playing audio tracks to one item, but you might as well create a DJ theme that can play multiple items at the same time.

Elements

The (web) components of the system. These are then recombined into an entire music player experience, or whatever you want to build.

Configurators

Elements that serve as an intermediate 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.

  • [todo] Input
    Add multiple inputs.
  • [todo] Output
    Allows the user to configure a specific output.
  • [todo] Scrobbles
    Configure multiple scrobblers (music trackers).

Engines

Elements with each a singular purpose and don't have any UI. There are specialised UI and orchestrator elements that control these.

  • Audio
    Plays audio through audio elements.
  • Queue
    A simple queue for tracks. NOTE: Temporarily automatically adds tracks shuffled to the queue.

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.

  • Opensubsonic
    Add any (open)subsonic server.
  • [todo] S3
    AWS S3 and services that provide the same surface API such as Cloudflare R2.

Orchestrators

These too are element compositions. However, unlike themes, these are purely logical. Mostly exist in order to construct sensible defaults to use across themes and other compositions.

  • Process inputs into tracks
    Whenever the cached tracks are initially loaded through the passed output element it will contextualize and then 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.
  • Queue ⭤ Tracks
    Sets the given queue element pool whenever the tracks signal from the given output changes.
  • Search ⭤ Tracks
    Supplies tracks to the given search processor whenever the tracks collection changes.

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.

  • Polymorphic / IndexedDB
    Stores output into the local indexedDB. Supports any type of data that indexedDB supports.

Processors

These elements work with the output generated by the input elements to add more data to them, or process them in some other way.

  • Artwork
    Fetches cover art for a given set of tracks, stored locally in indexedDB. Checks the audio metadata first, then MusicBrainz and uses Last.fm as the fallback.
  • Metadata
    Fetch audio metadata for a given set of tracks, adding to the `Track` object.
  • Search
    Provides a way to search through a collection of tracks, powered by orama.js

Supplements

Additional elements, such as scrobblers.

  • [todo] Last.fm scrobbler
  • [todo] ListenBrainz scrobbler
  • [todo] Rocksky scrobbler
  • [todo] Teal.fm scrobbler

Transformers

Transform data from one format or schema into another. See schema 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 / Cambria lenses
    Uses the Cambria library to seamlessly translate between data schemas so that no data migration is needed.
  • [todo] Output / Bytes / JSON
    Raw data schema output ⇄ JSON Uint8Array.
  • [todo] Output / String / JSON
    Raw data schema output ⇄ JSON UTF8 string.

Schemas

All of the elements here are built with these data schemas in mind. That said, you can mix elements that use different schemas; you just have to put a transformer between them in order to translate between the schemas.