Diffuse

Usage

The easiest way to start is by exploring the software. If you prefer a traditional prepackaged application approach, you can check out themes. Themes can look and function entirely different from each other, so make sure to explore!

Alternatively, there's facets which allows you to use any component from any theme interchangeably, among pieces that are not in themes; each in a separate browser tab. Each tab talks to each other, so you can for example browse audio in one tab and play it in another.

Diffuse is not your typical streaming service though, you have to add sources of audio. To start you can try out the demo by clicking the button below, or, go to a theme or facet that lets you add your audio input.

Themes

Themes are element compositions and provide a traditional browser web application way of using them. In other words, pretty much the whole thing, besides your data, lives inside a single browser tab.

Explore

Facets are various interface components each loaded in their own web page. Every used component is configured so that it operates in broadcast mode, making all the pages communicate with each other.

Explore

Agency

The goal is for every user, no matter their experience, to have agency over their data and their software. One can start with making small changes and gradually progress to making big changes.

Take control

Level 1: Pick your restaurant, food comes in all shapes and sizes. The equivalent of choosing a Diffuse theme.

Level 2: Take out food from various places, eg. cheese shop + bakery. You choose how you combine the foods and from where you order them. That's facets.

Level 3: Now that you know which food is good and how to make combinations, you might make a slight customization, add a little something of your own (eg. add some spice). However, you're not quite confident enough which spice to pick, so you hire some help.

This can be done using the facets builder which allows you to build on top of a familiar preconfigured foundation and load custom facets. People might share their own, or maybe you use an LLM to generate something for you (eg. an album art gallery).

Level 4: You learned a bit from watching and talking to the help you hired, so you decide to take things in your own hands.

You continue to use the facets builder but learn a bit of HTML, Javascript and CSS; so you're able to write your own facet.

Level 5: At this point you're confident enough to make a meal from scratch. You can start very simple, eg. just throwing a steak in the pan with some butter and some salt to it. Then later add some baked potatoes and go from there.

A similar tool comes into play here, the themes builder. Same concept as the facets builder, but now you need to specify the foundation yourself. You can use the elements listed below to do so. The code for these is available from this website or through the Javascript package.

Level 6: You open your own restaurant.

You can host the theme you made on any web server, it's only HTML after all. Only difference is that you'll have to create the entire HTML tree, not just the body element, as is the case with the theme builder.

Level 7: You got promoted to master chef. Time to open your own restaurant chain.

You can self-host Diffuse, it's open-source! Or you present your own collection of elements.

Elements

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

Consume these using the facets builder, the Javascript package, or the linked Javascript files down below.

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.

Input
Allows for multiple inputs to be used at once.
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.
[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.
[todo] Favourites
Mark tracks as favourites. Automatically creates an unordered 'Favourites' playlist.
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.

Opensubsonic
Add any (open)subsonic server.
[todo] HTTPS (Raw)
Enables usage of tracks with a HTTPS URI.
[todo] HTTPS (JSON)
Generate tracks based on HTTPS servers that provide JSON (directory) listings.
S3
AWS S3 and services that provide the same surface API such as Cloudflare R2.
[todo] Soundcloud
Add items from your Soundcloud feed.
[todo] WebDAV
Add any WebDAV server.

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.

Automatic queue
Fill the queue automatically with non-manual items (shuffled or regular, based on repeat-shuffle engine).
Input
A default input configuration. Contains all the inputs provided here.
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.
Sources
Monitor tracks from the given output to form a list of sources based on the input's sources return value.
Scoped Tracks
Supplies the tracks from the given output to the given search processor whenever the tracks collection changes. Additionally it 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.

[todo] Bytes / Automerge Repo
Sync with an Automerge repo sync server.
Polymorphic / IndexedDB
Stores output into the local indexedDB. Supports any type of data that indexedDB supports.
[todo] 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.

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.

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 / JSON
Raw data schema output ⇄ JSON Uint8Array.
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 / 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.

Output / Facet
Facet pointer or HTML snippet.
Output / Playlist
Represents a collection of tracks, which may be ordered or unordered. Tracks are matched based on the given criteria.
[todo] Output / Progress
Used to track progress of (long) audio playback.
Output / Theme
Theme pointer or HTML snippet.
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. This object may be cached if convenient.