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