tokono.ma
A music player that connects to your cloud/distributed storage.
docs: add contributing.md & update readme
-18
AGENTS.md
-18
AGENTS.md
···
1
-
# Agent guide
2
-
3
-
Before you write any code, read:
4
-
5
-
- The **why** document: `src/index.vto`
6
-
(there might be a compiled version `dist/index.html`, if so prefer that)
7
-
- The **how** document: `docs/ARCHITECTURE.md`
8
-
9
-
10
-
## Your responsibilities
11
-
12
-
As an agent, your job is to:
13
-
- Keep the architecture described in `docs/ARCHITECTURE.md` intact.
14
-
- Preserve the overall goals and constraints described in the 'why' document.
15
-
16
-
If you are unsure how to implement something:
17
-
- Prefer a small, clean, testable implementation that matches the intent.
18
-
- Do **not** invent new architecture without clear justification in comments.
···
+7
CONTRIBUTING.md
+7
CONTRIBUTING.md
···
···
1
+
# Welcome 👋
2
+
3
+
Thanks for considering to contribute! To get started, take a look at the following items:
4
+
5
+
- **`README.md`**: Also in the root of this project, along side this file, for some general context and build instructions.
6
+
- **Explainer web page**: Important context, explains all non-technical aspects. You can either check out the [last deployed version](https://elements.diffuse.sh/latest/), or build the version located in this repo (`deno run build` → `dist/index.html`, or alternatively: `deno run serve` and open `http://localhost:3000`)
7
+
- **Architecture docs**: Another important piece, talks about code and file/directory organisation. Located in `docs/`.
+35
-4
README.md
+35
-4
README.md
···
1
<img src="https://diffuse.sh/images/diffuse-light.svg" alt="Diffuse" width="158" />
2
3
-
**Construct your audio player**, make a music player by composing web components.
4
5
Diffuse provides a range of custom elements: audio input, data output, metadata & artwork processing, audio playback, a queue system, and much more.
6
7
-
It also features themes which are prebuilt compositions of those elements.
8
9
-
More information on the [website](https://elements.diffuse.sh).
10
11
12
## Build it yourself
···
15
16
```shell
17
deno run gen:defs:types
18
-
deno run build
19
```
···
1
<img src="https://diffuse.sh/images/diffuse-light.svg" alt="Diffuse" width="158" />
2
3
+
**Construct your audio player**, make a music player and browser by composing web components.
4
5
Diffuse provides a range of custom elements: audio input, data output, metadata & artwork processing, audio playback, a queue system, and much more.
6
7
+
It is also aimed at consumers, providing themes and constituents, preconfigured component compositions; while simultaneously trying to be [malleable software](https://www.inkandswitch.com/essay/malleable-software/).
8
+
9
+
More information on the [website](https://elements.diffuse.sh/latest/).
10
+
11
+
12
+
## Developer usage
13
+
14
+
You can either consume the Diffuse library via the [deployed instance](https://elements.diffuse.sh/latest/) (the listed elements link to Javascript files) or the [Javascript package](https://jsr.io/@toko/diffuse).
15
+
16
+
From there you can use the custom elements as with any other custom DOM element, by writing HTML or creating a `Class` instance.
17
+
18
+
```html
19
+
<script src="https://elements.diffuse.sh/bafybeiezh4rgv7gk73o5dalfyilv5nfopezyvshtj5j7hrn23r4n27k7da/components/engine/queue/element.js"></script>
20
+
21
+
<de-queue></de-queue>
22
+
```
23
+
24
+
```js
25
+
import QueueEngine from "@toko/diffuse/components/engine/queue/element.js"
26
27
+
const queue = new QueueEngine()
28
+
queue.setAttribute("group", "constituents")
29
+
30
+
document.body.append(queue)
31
+
````
32
33
34
## Build it yourself
···
37
38
```shell
39
deno run gen:defs:types
40
+
deno run build # or deno run build
41
```
42
+
43
+
Diffuse is built with:
44
+
- [Deno](https://deno.com)
45
+
- Web components (custom elements)
46
+
- Web workers (also: shared + service workers)
47
+
- Signals (currently alien-signals, but hopefully [TC39](https://github.com/tc39/proposal-signals) in the future)
48
+
- [`lit-html`](https://lit.dev/docs/libraries/standalone-templates/)
49
+
- [`music-metadata`](https://github.com/Borewit/music-metadata)
50
+
- Lume & ESBuild