---
layout: layouts/diffuse.vto

styles:
  - styles/base.css
  - styles/diffuse/page.css
  - vendor/@phosphor-icons/bold/style.css
  - vendor/@phosphor-icons/fill/style.css

scripts:
  - index.js

# ELEMENTS

configurators:
  - url: "components/configurator/input/element.js"
    title: "Input"
    desc: "Allows for multiple inputs to be used at once."
  - url: "components/configurator/output/element.js"
    title: "Output"
    desc: "Enables the user to configure a specific output. If no default output is set, it creates a temporary session by storing everything in memory."
  - url: "components/configurator/scrobbles/element.js"
    title: "Scrobbles"
    desc: "Configure multiple scrobblers (music trackers)."
    todo: true

engines:
  - url: "components/engine/audio/element.js"
    title: "Audio"
    desc: "Plays audio through audio elements."
  - url: "components/engine/queue/element.js"
    title: "Queue"
    desc: "A queue for tracks."
  - url: "components/engine/repeat-shuffle/element.js"
    title: "Repeat & Shuffle"
    desc: "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."
  - url: "components/engine/scope/element.js"
    title: "Scope"
    desc: >
      Signals that could influence the scope of a set of tracks.

input:
  - url: "components/input/https/element.js"
    title: "HTTPS"
    desc: >
      HTTPS URLs to audio files or streams.
  - title: "HTTPS (JSON)"
    desc: >
      Generate tracks based on HTTPS servers that provide JSON (directory) listings.
    todo: true
  - url: "components/input/local/element.js"
    title: "Local"
    desc: >
      Audio files or directories from your local device, using the browser's File System Access API.
  - url: "components/input/opensubsonic/element.js"
    title: "Opensubsonic"
    desc: >
      Add any (open)subsonic server.
  - url: "components/input/s3/element.js"
    title: "S3"
    desc: >
      AWS S3 and services that provide the same surface API such as Cloudflare R2.
  - title: "WebDAV"
    desc: >
      Add any WebDAV server.
    todo: true

orchestrators:
  - url: "components/orchestrator/auto-queue/element.js"
    title: "Automatic queue"
    desc: >
      Fill the queue automatically with non-manual items (shuffled or regular, based on repeat-shuffle engine).
  - url: "components/orchestrator/favourites/element.js"
    title: "Favourites"
    desc: >
      Mark tracks as favourites. Automatically creates an unordered 'Favourites' playlist.
  - url: "components/orchestrator/input/element.js"
    title: "Input"
    desc: "**A default input configuration.** Contains all the inputs provided here."
  - url: "components/orchestrator/media-session/element.js"
    title: "Media Session"
    desc: "Keeps the browser/os media session in sync with queue and audio state. Adds handlers for previous, next, seek to, etc."
  - url: "components/orchestrator/output/element.js"
    title: "Output"
    desc: "**A default output configuration.** Contains all the outputs provided here along with the relevant transformers."
  - url: "components/orchestrator/process-tracks/element.js"
    title: "Process inputs into tracks"
    desc: "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."
  - url: "components/orchestrator/queue-audio/element.js"
    title: "Queue ⭤ Audio"
    desc: "Connects the given queue engine to the given audio engine."
  - url: "components/orchestrator/sources/element.js"
    title: "Sources"
    desc: "Monitor tracks from the given output to form a list of sources based on the input's sources return value."
  - url: "components/orchestrator/scoped-tracks/element.js"
    title: "Scoped Tracks"
    desc: "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:
  - url: "components/output/polymorphic/indexed-db/element.js"
    title: "Polymorphic / IndexedDB"
    desc: "Stores output into the local indexedDB. Supports any type of data that indexedDB supports."
  - url: "components/output/bytes/s3/element.js"
    title: "Bytes / S3"
    desc: >
      Store output data on AWS S3 or compatible services such as Cloudflare R2.
  - url: "components/output/raw/atproto/element.js"
    title: "Raw / AT Protocol"
    desc: >
      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:
  - url: "components/processor/artwork/element.js"
    title: "Artwork"
    desc: "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."
  - url: "components/processor/metadata/element.js"
    title: "Metadata"
    desc: "Fetch audio metadata for a given set of tracks, adding to the `Track` object."
  - url: "components/processor/search/element.js"
    title: "Search"
    desc: "Provides a way to search through a collection of tracks, powered by orama.js"

supplements:
  - title: "Last.fm scrobbler"
    todo: true
  - title: "ListenBrainz scrobbler"
    todo: true
  - title: "Rocksky scrobbler"
    todo: true
  - title: "Teal.fm scrobbler"
    todo: true

transformers:
  - title: "Output / Bytes / Automerge"
    desc: "Translate data to and from an Automerge CRDT."
    url: "components/transformer/output/bytes/automerge/element.js"
    todo: true
  - title: "Output / Bytes / Cambria lenses"
    desc: "Uses the Cambria library to seamlessly translate between data schemas so that no data migration is needed."
    todo: true
  - title: "Output / Bytes / DASL Sync"
    desc: "Syncs data between local and remote using CID-based diffing and performs union merges with tombstone tracking when both sides have diverged."
    url: "components/transformer/output/bytes/dasl-sync/element.js"
  - title: "Output / Bytes / JSON"
    desc: "Raw data schema output ⇄ JSON Uint8Array."
    url: "components/transformer/output/bytes/json/element.js"
  - title: "Output / Raw / AT Protocol Sync"
    desc: "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."
    url: "components/transformer/output/raw/atproto-sync/element.js"
  - title: "Output / Refiner / Default"
    desc: "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.**"
    url: "components/transformer/output/refiner/default/element.js"
  - title: "Output / Refiner / Track URI Passkey"
    desc: "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."
    url: "components/transformer/output/refiner/track-uri-passkey/element.js"
  - title: "Output / String / JSON"
    desc: "Raw data schema output ⇄ JSON UTF8 string."
    url: "components/transformer/output/string/json/element.js"

# DEFINITIONS

definitions:
  - title: "Output / Collaboration"
    desc: >
      Represents a collaboration between multiple collaborators on a subject, such as a playlist.
    url: "definitions/output/collaboration.json"
  - title: "Output / Facet"
    desc: >
      Facet pointer or HTML snippet.
    url: "definitions/output/facet.json"
  - title: "Output / Playlist Item"
    desc: >
      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.
    url: "definitions/output/playlistItem.json"
  - title: "Output / Playlist Item Bundle"
    desc: >
      A bundle of playlist items.
    url: "definitions/output/playlistItemBundle.json"
  - title: "Output / Progress"
    desc: >
      Used to track progress of (long) audio playback.
    todo: true
  - title: "Output / Theme"
    desc: >
      Theme pointer or HTML snippet.
    url: "definitions/output/theme.json"
  - title: "Output / Track"
    desc: >
      Represents audio that can be played, or a placeholder for a source of tracks. Contains a URI that will resolve to the audio.
    url: "definitions/output/track.json"
  - title: "Output / Track Bundle"
    desc: >
      A bundle of tracks.
    url: "definitions/output/trackBundle.json"

---

<header>
  <div>
    <h1 class="diffuse-logo">
      {{ await comp.diffuse.logo() }}
      <span id="status">
        <a href="/latest/" title="Upgrade to latest" class="animate-spin">
          <i class="ph-bold ph-spinner"></i>
        </a>
        <a href="/chronicle/" title="Browse versions of Diffuse">
          <i class="ph-fill ph-star-four"></i>
        </a>
      </span>
    </h1>
    <p class="construct dither-mask">
      Your audio<br />your data<br />your rules
    </p>
    <p>
      Diffuse is a collection of components and software that make it possible to listen to audio from various sources on your devices and the web, and to create the ideal digital audio listening experience for you.
    </p>
    <p style="align-items: center; display: flex; gap: var(--space-2xs); opacity: 0.55;">
      <i class="ph-fill ph-crane"></i>
      <strong style="font-weight: 700;">WORK IN PROGRESS</strong>
    </p>
    <ul class="table-of-contents">
      <li><a href="#usage">Usage</a></li>
      <li><a href="#themes">Themes</a></li>
      <li><a href="#facets">Facets</a></li>
      <li><a href="#agency">Agency</a></li>
      <li><a href="#elements">Elements</a></li>
      <li><a href="#definitions">Definitions</a></li>
    </ul>
    <p>
      <small>Built by <a href="https://tokono.ma">tokono.ma</a></small>
    </p>
  </div>
  <div class="dither-mask filler"></div>
</header>
<main>
  <!-- USAGE -->
  <section>
    <h2 id="usage">Usage</h2>

    <div class="columns">
      <div class="element">
        <p>
          The easiest way to start is by exploring the software. If you prefer a traditional pre&shy;packaged application approach, you can check out <a href="themes/">themes</a>. Themes can look and function entirely different from each other, so make sure to explore!
        </p>

        <p>
          Alternatively, there's <a href="facets/">facets</a> which allows you to use any component from any theme interchange&shy;ably, 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.
        </p>
      </div>

      <div class="element">
        <p>
          <strong style="color: var(--accent); font-weight: 700;">Diffuse is not your typical streaming service though, you have to add sources of audio.</strong> To start you can try out the demo by clicking the button below, or, go to a <a href="themes/">theme</a> or <a href="facets/">facet</a> that lets you add your audio input.
        </p>

        <p>
          <button id="add-sample-content">
            <span>Add sample content</span>
          </button>
        </p>
      </div>
    </div>
  </section>

  <!-- THEMES & FACETS -->
  <div class="columns">
    <section>
      <h2 id="themes">Themes</h2>

      <p>
        Themes each provide a traditional browser web application built on the Diffuse elements. They focus on delivering <strong>a great encompassing experience in a single window</strong>. They represent the opposite of facets, but can optionally delegate functionality to facets if they wish to do so.
      </p>

      <p>
        <a class="button button--alt" href="themes/">Explore</a>
      </p>
    </section>

    <section>
      <h2 id="facets">Facets</h2>

      <p>
        Facets are various user interfaces, with their own logic, each loaded in their own web page. Every used Diffuse component is configured so that it operates in broadcast mode, making all the pages communicate with each other. <strong>You choose the features you want in your software.</strong>
      </p>

      <p>
        <a class="button button--alt" href="facets/">Explore</a>
      </p>
    </section>
  </div>

  <!-- AGENCY -->
  <section>
    <h2 id="agency">Agency</h2>

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

    <p>
      You can store your user-data in various places, and easily export, import and sync it.
    </p>

    <h3>Take control</h3>

    <ul class="columns">
      <div class="element">
        <!-- 1 -->
        <li>
          <p>
            <i class="ph-fill ph-storefront"></i> <strong>Level 1</strong>: Pick your restaurant, food comes in all shapes and sizes. The equivalent of choosing a Diffuse <a href="themes/">theme</a>.
          </p>
        </li>
        <!-- 2 -->
        <li>
          <p>
            <i class="ph-fill ph-basket"></i> <strong>Level 2</strong>: 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 <a href="facets/">facets</a>.
          </p>
        </li>
        <!-- 3 -->
        <li>
          <p>
            <i class="ph-fill ph-pepper"></i> <strong>Level 3</strong>: 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.
          </p>
          <p>
            This can be done using the <a href="facets/#builder">facets builder</a> 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).
          </p>
        </li>
        <!-- 4 -->
        <li>
          <p>
            <i class="ph-fill ph-knife"></i> <strong>Level 4</strong>: You learned a bit from watching and talking to the help you hired, so you decide to take things in your own hands.
          </p>
          <p>
            You continue to use the <a href="facets/#builder">facets builder</a> but learn a bit of <a href="https://htmlforpeople.com">HTML</a>, <a href="https://javascript.info">Javascript</a> and <a href="https://htmlforpeople.com/css-basics/">CSS</a>; so you're able to write your own facet.
          </p>
        </li>
      </div>
      <div class="element">
        <!-- 5 -->
        <li>
          <p>
            <i class="ph-fill ph-cooking-pot"></i> <strong>Level 5</strong>: 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.
          </p>
          <p>
            A similar tool comes into play here, the <a href="themes/#builder">themes builder</a>. Same concept as the facets builder, but now you need to specify the foundation yourself. You can use the <a href="#elements">elements</a> listed below to do so. The code for these is available from this website or through the <a href="https://jsr.io/@toko/diffuse">Javascript package</a>.
          </p>
        </li>
        <!-- 6 -->
        <li>
          <p>
            <i class="ph-fill ph-storefront"></i> <strong>Level 6</strong>: You open your own restaurant.
          </p>
          <p>
            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.
          </p>
        </li>
        <!-- 7 -->
        <li>
          <p>
            <i class="ph-fill ph-chef-hat"></i> <strong>Level 7</strong>: You got promoted to master chef. Time to open your own restaurant chain.
          </p>
          <p>
            You can self-host Diffuse, it's <a href="https://tangled.org/tokono.ma/diffuse/blob/v4/">open-source</a>! Or you present your own collection of elements.
          </p>
        </li>
      </div>
    </ul>
  </section>

  <!-- ELEMENTS -->
  <section>
    <h2 id="elements">Elements</h2>

    <p>
      The (web) components of the system. These custom elements are then recombined into an entire music player and browser, or whatever you want to build.
    </p>

    <p>
      Consume these using the facets <a href="facets/#builder">builder</a>, the Javascript <a href="https://jsr.io/@toko/diffuse">package</a>, or the linked Javascript files down below.
    </p>

    <div class="columns">
      {{ await comp.element({
        title: "Configurators",
        items: configurators,
        content: `
          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.
        `
      }) }}

      {{ await comp.element({
        title: "Engines",
        items: engines,
        content: `
          Elements with each a singular purpose and don't have any UI. There are specialised UI and orchestrator elements that control these.
        `
      }) }}

      {{ await comp.element({
        title: "Input",
        items: input,
        content: `
        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.
        `
      }) }}

      {{ await comp.element({
        title: "Orchestrators",
        items: orchestrators,
        content: `
        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.
        `
      }) }}

      {{ await comp.element({
        title: "Output",
        items: output,
        content: `
        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.
        `
      }) }}

      {{ await comp.element({
        title: "Processors",
        items: processors,
        content: `
        These elements work with the output generated by the input elements to add more data to them, or process them in some other way.
        `
      }) }}

      {{ await comp.element({
        title: "Supplements",
        items: supplements,
        content: `
        Additional elements, such as scrobblers.
        `
      }) }}

      {{ await comp.element({
        title: "Transformers",
        items: transformers,
        content: `
        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.
        `
      }) }}
    </div>
  </section>

  <!-- DEFINITIONS -->
  <section>
    <h2 id="definitions">Definitions</h2>

    <p>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.</p>

    {{ await comp.list({ items: definitions }) }}
  </section>
</main>