forked from
tokono.ma/diffuse
A music player that connects to your cloud/distributed storage.
1---
2layout: layouts/diffuse.vto
3base: ../
4title: Elements | Diffuse
5
6styles:
7 - styles/base.css
8 - styles/diffuse/page.css
9 - vendor/@phosphor-icons/web/bold/style.css
10 - vendor/@phosphor-icons/web/fill/style.css
11
12# ELEMENTS
13
14artwork:
15 - url: "components/artwork/audio-metadata/element.js"
16 title: "Audio Metadata"
17 desc: "Extracts embedded artwork from audio files using the music-metadata library."
18 - url: "components/artwork/last.fm/element.js"
19 title: "Last.fm"
20 desc: "Fetches cover art from the Last.fm API using track artist and album tags."
21 - url: "components/artwork/musicbrainz/element.js"
22 title: "MusicBrainz"
23 desc: "Fetches cover art from MusicBrainz and the Cover Art Archive using track artist and album tags."
24
25configurators:
26 - url: "components/configurator/artwork/element.js"
27 title: "Artwork"
28 desc: "Takes artwork components as children and tries each in sequence, returning the first non-null result."
29 - url: "components/configurator/input/element.js"
30 title: "Input"
31 desc: "Allows for multiple inputs to be used at once."
32 - url: "components/configurator/metadata/element.js"
33 title: "Metadata"
34 desc: "Takes metadata components as children and chains their patches in sequence."
35 - url: "components/configurator/output/element.js"
36 title: "Output"
37 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."
38 - url: "components/configurator/scrobbles/element.js"
39 title: "Scrobbles"
40 desc: "Configure multiple scrobblers (music trackers)."
41
42engines:
43 - url: "components/engine/audio/element.js"
44 title: "Audio"
45 desc: "Plays audio through audio elements."
46 - url: "components/engine/queue/element.js"
47 title: "Queue"
48 desc: "A queue for tracks."
49 - url: "components/engine/repeat-shuffle/element.js"
50 title: "Repeat & Shuffle"
51 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."
52 - url: "components/engine/scope/element.js"
53 title: "Scope"
54 desc: >
55 Signals that could influence the scope of a set of tracks.
56
57input:
58 - url: "components/input/https/element.js"
59 title: "HTTPS"
60 desc: >
61 HTTPS URLs to audio files or streams.
62 - title: "HTTPS (JSON)"
63 desc: >
64 Generate tracks based on HTTPS servers that provide JSON (directory) listings.
65 todo: true
66 - url: "components/input/icecast/element.js"
67 title: "Icecast"
68 desc: >
69 Icecast internet radio streams. Fetches ICY metadata to populate track information.
70 - url: "components/input/local/element.js"
71 title: "Local"
72 desc: >
73 Audio files or directories from your local device, using the browser's File System Access API.
74 - url: "components/input/opensubsonic/element.js"
75 title: "Opensubsonic"
76 desc: >
77 Add any (open)subsonic server.
78 - url: "components/input/s3/element.js"
79 title: "S3"
80 desc: >
81 AWS S3 and services that provide the same surface API such as Cloudflare R2.
82 - title: "WebDAV"
83 desc: >
84 Add any WebDAV server.
85 todo: true
86
87orchestrators:
88 - url: "components/orchestrator/auto-queue/element.js"
89 title: "Automatic Queue"
90 desc: >
91 Fill the queue automatically with non-manual items (shuffled or regular, based on repeat-shuffle engine).
92 - url: "components/orchestrator/favourites/element.js"
93 title: "Favourites"
94 desc: >
95 Mark tracks as favourites. Automatically creates an unordered 'Favourites' playlist.
96 - url: "components/orchestrator/input/element.js"
97 title: "Input"
98 desc: "**A default input configuration.** Contains all the inputs provided here."
99 - url: "components/orchestrator/media-session/element.js"
100 title: "Media Session"
101 desc: "Keeps the browser/os media session in sync with queue and audio state. Adds handlers for previous, next, seek to, etc."
102 - url: "components/orchestrator/offline/element.js"
103 title: "Offline"
104 desc: "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."
105 - url: "components/orchestrator/output/element.js"
106 title: "Output"
107 desc: "**A default output configuration.** Contains all the outputs provided here along with the relevant transformers."
108 - url: "components/orchestrator/path-collections/element.js"
109 title: "Path Collections"
110 desc: "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."
111 - url: "components/orchestrator/process-tracks/element.js"
112 title: "Process Inputs Into Tracks"
113 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."
114 - url: "components/orchestrator/queue-audio/element.js"
115 title: "Queue ⭤ Audio"
116 desc: "Connects the given queue engine to the given audio engine."
117 - url: "components/orchestrator/scrobble-audio/element.js"
118 title: "Scrobble ⭤ Audio"
119 desc: "Connects the audio engine with a scrobbler element. Calls `nowPlaying` when a track starts playing and `scrobble` once the user has listened long enough."
120 - url: "components/orchestrator/sources/element.js"
121 title: "Sources"
122 desc: "Monitor tracks from the given output to form a list of sources based on the input's sources return value."
123 - url: "components/orchestrator/artwork/element.js"
124 title: "Artwork"
125 desc: "Fetches cover art for a given set of tracks, stored locally in indexedDB. Uses the artwork configurator to try each configured source in sequence."
126 - url: "components/orchestrator/scoped-tracks/element.js"
127 title: "Scoped Tracks"
128 desc: "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`"
129
130output:
131 - url: "components/output/polymorphic/indexed-db/element.js"
132 title: "Polymorphic / IndexedDB"
133 desc: "Stores output into the local indexedDB. Supports any type of data that indexedDB supports."
134 - url: "components/output/bytes/s3/element.js"
135 title: "Bytes / S3"
136 desc: >
137 Store output data on AWS S3 or compatible services such as Cloudflare R2.
138 - url: "components/output/raw/atproto/element.js"
139 title: "Raw / AT Protocol"
140 desc: >
141 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.
142
143metadata:
144 - url: "components/metadata/audio-file/element.js"
145 title: "Audio File"
146 desc: "Extracts tags and audio stats from audio files using the music-metadata library."
147
148supplements:
149 - url: "components/supplement/last.fm/element.js"
150 title: "Last.fm Scrobbler"
151 - title: "ListenBrainz Scrobbler"
152 todo: true
153 - title: "Rocksky Scrobbler"
154 todo: true
155 - title: "Teal.fm Scrobbler"
156 todo: true
157
158transformers:
159 - title: "Output / Bytes / Automerge"
160 desc: "Translate data to and from an Automerge CRDT."
161 url: "components/transformer/output/bytes/automerge/element.js"
162 todo: true
163 - title: "Output / Bytes / Cambria Lenses"
164 desc: "Uses the Cambria library to seamlessly translate between data schemas so that no data migration is needed."
165 todo: true
166 - title: "Output / Bytes / DASL Sync"
167 desc: "Syncs data between local and remote using CID-based diffing and performs union merges with tombstone tracking when both sides have diverged."
168 url: "components/transformer/output/bytes/dasl-sync/element.js"
169 - title: "Output / Bytes / JSON"
170 desc: "Raw data schema output ⇄ JSON Uint8Array."
171 url: "components/transformer/output/bytes/json/element.js"
172 - title: "Output / Raw / AT Protocol Sync"
173 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."
174 url: "components/transformer/output/raw/atproto-sync/element.js"
175 - title: "Output / Refiner / Default"
176 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.**"
177 url: "components/transformer/output/refiner/default/element.js"
178 - title: "Output / Refiner / Track URI Passkey"
179 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."
180 url: "components/transformer/output/refiner/passkey-encryption/element.js"
181 - title: "Output / String / JSON"
182 desc: "Raw data schema output ⇄ JSON UTF8 string."
183 url: "components/transformer/output/string/json/element.js"
184
185# DEFINITIONS
186
187definitions:
188 - title: "Output / Collaboration"
189 desc: >
190 Represents a collaboration between multiple collaborators on a subject, such as a playlist.
191 url: "definitions/output/collaboration.json"
192 - title: "Output / Facet"
193 desc: >
194 Facet pointer or HTML snippet.
195 url: "definitions/output/facet.json"
196 - title: "Output / Playlist Item"
197 desc: >
198 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.
199 url: "definitions/output/playlistItem.json"
200 - title: "Output / Progress"
201 desc: >
202 Used to track progress of (long) audio playback.
203 todo: true
204 - title: "Output / Track"
205 desc: >
206 Represents audio that can be played, or a placeholder for a source of tracks. Contains a URI that will resolve to the audio.
207 url: "definitions/output/track.json"
208 - title: "Output / Track Bundle"
209 desc: >
210 A bundle of tracks.
211 url: "definitions/output/trackBundle.json"
212
213---
214
215<header>
216 <div>
217 <div class="diffuse-logo-container">
218 <a href="./" style="display: inline-block;">
219 {{ await comp.diffuse.logo() }}
220 </a>
221 {{ await comp.diffuse.status() }}
222 </div>
223 <p class="construct dither-mask">
224 Elements
225 </p>
226 <p>
227 Diffuse was built using these web components, consume these using the <a href="../code/">code tool</a>, the Javascript <a href="https://jsr.io/@toko/diffuse">package</a>, or the linked Javascript files down below.
228 </p>
229 <ul class="table-of-contents">
230 <li><a href="elements/#artwork">Artwork</a></li>
231 <li><a href="elements/#configurators">Configurators</a></li>
232 <li><a href="elements/#engines">Engines</a></li>
233 <li><a href="elements/#input">Input</a></li>
234 <li><a href="elements/#metadata">Metadata</a></li>
235 <li><a href="elements/#orchestrators">Orchestrators</a></li>
236 <li><a href="elements/#output">Output</a></li>
237 <li><a href="elements/#supplements">Supplements</a></li>
238 <li><a href="elements/#transformers">Transformers</a></li>
239 <!---->
240 <li style="margin-top: var(--space-xs);"><a href="#definitions">Definitions</a></li>
241 </ul>
242 </div>
243 <div class="dither-mask filler"></div>
244</header>
245<main>
246 <!-- ELEMENTS -->
247 <section>
248 <div class="columns">
249 {{ await comp.element({
250 title: "Artwork",
251 items: artwork,
252 content: `
253 Elements that provide artwork for tracks.
254 `
255 }) }}
256
257 {{ await comp.element({
258 title: "Configurators",
259 items: configurators,
260 content: `
261 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.
262 `
263 }) }}
264
265 {{ await comp.element({
266 title: "Engines",
267 items: engines,
268 content: `
269 Elements with each a singular purpose. There are orchestrator elements that control these.
270 `
271 }) }}
272
273 {{ await comp.element({
274 title: "Input",
275 items: input,
276 content: `
277 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.
278 `
279 }) }}
280
281 {{ await comp.element({
282 title: "Metadata",
283 items: metadata,
284 content: `
285 Elements that provide metadata for tracks.
286 `
287 }) }}
288
289 {{ await comp.element({
290 title: "Orchestrators",
291 items: orchestrators,
292 content: `
293 These are element compositions, logic only. Mostly exist in order to construct sensible defaults.
294 `
295 }) }}
296
297 {{ await comp.element({
298 title: "Output",
299 items: output,
300 content: `
301 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.
302 `
303 }) }}
304
305 {{ await comp.element({
306 title: "Supplements",
307 items: supplements,
308 content: `
309 Additional elements, such as scrobblers.
310 `
311 }) }}
312
313 {{ await comp.element({
314 title: "Transformers",
315 items: transformers,
316 content: `
317 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.
318 `
319 }) }}
320 </div>
321 </section>
322
323 <!-- DEFINITIONS -->
324 <section>
325 <h2 id="definitions" style="color: var(--accent)">Definitions</h2>
326
327 <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>
328
329 {{ await comp.list({ items: definitions }) }}
330 </section>
331</main>
332
333<script type="module">
334 import { versionUpgrade } from "./common/pages/version-upgrade.js";
335 versionUpgrade();
336</script>