web3-radio 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# web3-radio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Live audio streaming on [Swarm](https://www.ethswarm.org). Drop a publisher or a player into any web page — plain JavaScript, React, Svelte, whatever you use.
+
+**Try it:** [go live](https://bzz.limo/bzz/9b1fd340700c4408818f6644cb846bd5d5f85574e7b36f3df0b06e72de44c4ee/), then share the listener link it gives you. The [player](https://bzz.limo/bzz/fb7a8f6cc9135f303991ea80dd7ce2ef1c50ea553f6621ba475b5adaa6457ebe/) takes `?owner=…&stream=…`.
+
+## Install
+
+```sh
+npm install web3-radio
+```
+
+## Go live
+
+```html
+<div id="radio"></div>
+
+<script type="module">
+  import { Publisher } from 'web3-radio'
+
+  const publisher = new Publisher('#radio', { stream: 'my-show' })
+
+  console.log('Listeners need this owner address:', publisher.owner)
+</script>
+```
+
+Press the button, allow the microphone, and you are on air.
+
+A stream is identified by its **owner** (the publisher's address) and its **stream** name. Without a `privateKey`, a new identity is generated on every page load. Pass your own to keep the same address:
+
+```js
+new Publisher('#radio', { stream: 'my-show', privateKey: '0x…' })
+```
+
+## Listen
+
+```html
+<div id="radio"></div>
+
+<script type="module">
+  import { Player } from 'web3-radio'
+
+  new Player('#radio', { owner: '0x…', stream: 'my-show' })
+</script>
+```
+
+## Theme
+
+Both components accept a `theme`. Every field is optional.
+
+```js
+new Player('#radio', {
+  owner: '0x…',
+  stream: 'my-show',
+  theme: {
+    background: '#16161d',
+    foreground: '#f4f4f6',
+    muted: '#8b8b99',
+    accent: '#ff5c39',
+    font: 'system-ui, sans-serif',
+    radius: '16px',
+  },
+})
+```
+
+## API
+
+### `new Publisher(target, options)`
+
+| Option           | Default            | Description                                            |
+| ---------------- | ------------------ | ------------------------------------------------------ |
+| `stream`         | —                  | Stream name                                            |
+| `privateKey`     | random             | Hex secp256k1 key that signs the stream                |
+| `stamp`          | —                  | Postage batch ID; not needed with the default gateway  |
+| `gateway`        | `https://bzz.limo` | Swarm gateway or Bee node URL                          |
+| `segmentSeconds` | `2`                | Length of each audio segment                           |
+| `bitrate`        | `64000`            | Opus bitrate in bits per second                        |
+| `theme`          | —                  | Partial `Theme`                                        |
+
+`publisher.owner`, `publisher.live`, `publisher.start()`, `publisher.stop()`, `publisher.destroy()`
+
+### `new Player(target, options)`
+
+| Option    | Default            | Description                   |
+| --------- | ------------------ | ----------------------------- |
+| `owner`   | —                  | Publisher address             |
+| `stream`  | —                  | Stream name                   |
+| `gateway` | `https://bzz.limo` | Swarm gateway or Bee node URL |
+| `theme`   | —                  | Partial `Theme`               |
+
+`player.playing`, `player.play()`, `player.stop()`, `player.destroy()`
+
+`target` is an element or a CSS selector. `destroy()` stops and removes the component — call it when your framework unmounts.
+
+## How it works
+
+The publisher records the microphone as Opus segments. Each segment is uploaded with `POST /bytes`, its root chunk is wrapped in a single-owner chunk, and that chunk is uploaded with `POST /soc`. Its identifier is the feed identifier of the next index, so this upload is also the feed update. The feed topic is the hash of the stream name, so owner + stream name locate the stream.
+
+The player polls `/feeds/{owner}/{topic}` for the latest index, fetches each new segment's single-owner chunk with `GET /chunks/{address}`, downloads the wrapped segment with `GET /bytes/{root}`, and plays them back to back.
+
+## Examples
+
+```sh
+npm install
+npm run dev
+```
+
+Open `/publisher.html`, go live, then open the listener link it shows.
+
+`npm run publish:examples` builds both pages as standalone files, uploads them with [etherchunk](https://github.com/Cafe137/etherchunk), and prints their links.

package/dist/chunk.d.ts

@@ -0,0 +1,16 @@
+export interface Chunk {
+    address: Uint8Array;
+    span: number;
+    data: Uint8Array;
+}
+export declare function chunkAddress(data: Uint8Array): Uint8Array;
+export declare function rootChunk(data: Uint8Array): Chunk;
+export declare function topic(stream: string): Uint8Array;
+export declare function feedIdentifier(topic: Uint8Array, index: number): Uint8Array;
+export declare function socAddress(identifier: Uint8Array, owner: string): Uint8Array;
+export declare class Signer {
+    readonly privateKey: Uint8Array;
+    readonly owner: string;
+    constructor(privateKey?: string);
+    sign(identifier: Uint8Array, chunk: Chunk): Uint8Array;
+}

package/dist/chunk.js

@@ -0,0 +1,69 @@
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { bytesToHex, concatBytes, hexToBytes, utf8ToBytes } from '@noble/hashes/utils.js';
+const CHUNK_SIZE = 4096;
+const REFS_PER_CHUNK = 128;
+function uint64(value, littleEndian) {
+    const bytes = new Uint8Array(8);
+    new DataView(bytes.buffer).setBigUint64(0, BigInt(value), littleEndian);
+    return bytes;
+}
+function bmt(payload) {
+    let level = new Uint8Array(CHUNK_SIZE);
+    level.set(payload);
+    while (level.length > 32) {
+        const parent = new Uint8Array(level.length / 2);
+        for (let i = 0; i < parent.length; i += 32)
+            parent.set(keccak_256(level.subarray(i * 2, i * 2 + 64)), i);
+        level = parent;
+    }
+    return level;
+}
+export function chunkAddress(data) {
+    return keccak_256(concatBytes(data.subarray(0, 8), bmt(data.subarray(8))));
+}
+function makeChunk(payload, span) {
+    const data = concatBytes(uint64(span, true), payload);
+    return { address: chunkAddress(data), span, data };
+}
+export function rootChunk(data) {
+    let level = [];
+    for (let i = 0; i < data.length; i += CHUNK_SIZE) {
+        const payload = data.subarray(i, i + CHUNK_SIZE);
+        level.push(makeChunk(payload, payload.length));
+    }
+    while (level.length > 1) {
+        const parents = [];
+        for (let i = 0; i < level.length; i += REFS_PER_CHUNK) {
+            const group = level.slice(i, i + REFS_PER_CHUNK);
+            const span = group.reduce((sum, chunk) => sum + chunk.span, 0);
+            parents.push(group.length === 1 ? group[0] : makeChunk(concatBytes(...group.map(chunk => chunk.address)), span));
+        }
+        level = parents;
+    }
+    return level[0];
+}
+export function topic(stream) {
+    return keccak_256(utf8ToBytes(stream));
+}
+export function feedIdentifier(topic, index) {
+    return keccak_256(concatBytes(topic, uint64(index, false)));
+}
+export function socAddress(identifier, owner) {
+    return keccak_256(concatBytes(identifier, hexToBytes(owner)));
+}
+export class Signer {
+    privateKey;
+    owner;
+    constructor(privateKey) {
+        this.privateKey = privateKey ? hexToBytes(privateKey.replace(/^0x/, '')) : secp256k1.utils.randomSecretKey();
+        const publicKey = secp256k1.getPublicKey(this.privateKey, false);
+        this.owner = bytesToHex(keccak_256(publicKey.subarray(1)).subarray(12));
+    }
+    sign(identifier, chunk) {
+        const digest = keccak_256(concatBytes(identifier, chunk.address));
+        const message = keccak_256(concatBytes(utf8ToBytes('\x19Ethereum Signed Message:\n32'), digest));
+        const signature = secp256k1.sign(message, this.privateKey, { prehash: false, format: 'recovered' });
+        return concatBytes(signature.subarray(1), new Uint8Array([27 + signature[0]]));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Player, type PlayerOptions } from './player.js';
+export { Publisher, type PublisherOptions } from './publisher.js';
+export { defaultTheme, type Target, type Theme } from './widget.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Player } from './player.js';
+export { Publisher } from './publisher.js';
+export { defaultTheme } from './widget.js';

package/dist/player.d.ts

@@ -0,0 +1,20 @@
+import { Target, Theme } from './widget.js';
+export interface PlayerOptions {
+    owner: string;
+    stream: string;
+    gateway?: string;
+    theme?: Partial<Theme>;
+}
+export declare class Player {
+    private readonly owner;
+    private readonly swarm;
+    private readonly topic;
+    private readonly widget;
+    private context?;
+    constructor(target: Target, options: PlayerOptions);
+    get playing(): boolean;
+    play(): void;
+    stop(): void;
+    destroy(): void;
+    private listen;
+}

package/dist/player.js

@@ -0,0 +1,70 @@
+import { topic } from './chunk.js';
+import { Swarm } from './swarm.js';
+import { Widget } from './widget.js';
+const POLL_MS = 1000;
+const BUFFER_SEGMENTS = 3;
+const MAX_LAG = 8;
+export class Player {
+    owner;
+    swarm;
+    topic;
+    widget;
+    context;
+    constructor(target, options) {
+        this.owner = options.owner.replace(/^0x/, '').toLowerCase();
+        this.swarm = new Swarm(options.gateway);
+        this.topic = topic(options.stream);
+        this.widget = new Widget(target, options.stream, options.theme, () => (this.playing ? this.stop() : this.play()));
+        this.widget.update(false, 'Tap to listen', 'Play');
+    }
+    get playing() {
+        return this.context !== undefined;
+    }
+    play() {
+        if (this.context)
+            return;
+        this.context = new AudioContext();
+        this.widget.update(true, 'Tuning in…', 'Stop');
+        this.listen(this.context);
+    }
+    stop() {
+        this.context?.close();
+        this.context = undefined;
+        this.widget.visualize();
+        this.widget.update(false, 'Tap to listen', 'Play');
+    }
+    destroy() {
+        this.stop();
+        this.widget.destroy();
+    }
+    async listen(context) {
+        const analyser = context.createAnalyser();
+        analyser.fftSize = 128;
+        analyser.connect(context.destination);
+        this.widget.visualize(analyser);
+        let next;
+        let time = 0;
+        while (context === this.context) {
+            try {
+                const latest = await this.swarm.latest(this.owner, this.topic);
+                if (next === undefined || latest - next > MAX_LAG)
+                    next = Math.max(0, latest - BUFFER_SEGMENTS);
+                for (; next <= latest; next++) {
+                    const source = context.createBufferSource();
+                    source.buffer = await context.decodeAudioData(await this.swarm.segment(this.owner, this.topic, next));
+                    source.connect(analyser);
+                    time = Math.max(time, context.currentTime + 0.1);
+                    source.start(time);
+                    time += source.buffer.duration;
+                }
+                if (context === this.context)
+                    this.widget.update(true, 'Live', 'Stop');
+            }
+            catch {
+                if (context === this.context)
+                    this.widget.update(true, 'Waiting for the stream…', 'Stop');
+            }
+            await new Promise(resolve => setTimeout(resolve, POLL_MS));
+        }
+    }
+}

package/dist/publisher.d.ts

@@ -0,0 +1,31 @@
+import { Target, Theme } from './widget.js';
+export interface PublisherOptions {
+    stream: string;
+    privateKey?: string;
+    stamp?: string;
+    gateway?: string;
+    segmentSeconds?: number;
+    bitrate?: number;
+    theme?: Partial<Theme>;
+}
+export declare class Publisher {
+    private readonly options;
+    readonly owner: string;
+    private readonly signer;
+    private readonly swarm;
+    private readonly topic;
+    private readonly widget;
+    private context?;
+    private media?;
+    private recorder?;
+    private timer?;
+    private index;
+    private active;
+    constructor(target: Target, options: PublisherOptions);
+    get live(): boolean;
+    start(): Promise<void>;
+    stop(): void;
+    destroy(): void;
+    private record;
+    private publish;
+}

package/dist/publisher.js

@@ -0,0 +1,95 @@
+import { Signer, topic } from './chunk.js';
+import { Swarm } from './swarm.js';
+import { Widget } from './widget.js';
+const MIME_TYPES = ['audio/webm;codecs=opus', 'audio/ogg;codecs=opus', 'audio/mp4;codecs=opus'];
+const describe = (error) => (error instanceof Error ? error.message : String(error));
+export class Publisher {
+    options;
+    owner;
+    signer;
+    swarm;
+    topic;
+    widget;
+    context;
+    media;
+    recorder;
+    timer;
+    index = 0;
+    active = false;
+    constructor(target, options) {
+        this.options = options;
+        this.signer = new Signer(options.privateKey);
+        this.owner = this.signer.owner;
+        this.swarm = new Swarm(options.gateway, options.stamp);
+        this.topic = topic(options.stream);
+        this.widget = new Widget(target, options.stream, options.theme, () => (this.live ? this.stop() : this.start()));
+        this.widget.update(false, 'Off air', 'Go live');
+    }
+    get live() {
+        return this.active;
+    }
+    async start() {
+        if (this.active)
+            return;
+        this.active = true;
+        this.widget.update(true, 'Going live…', 'Stop');
+        try {
+            const media = await navigator.mediaDevices.getUserMedia({ audio: true });
+            this.index = await this.swarm.latest(this.owner, this.topic).then(index => index + 1, () => 0);
+            if (!this.active)
+                return media.getTracks().forEach(track => track.stop());
+            this.media = media;
+            this.context = new AudioContext();
+            const analyser = this.context.createAnalyser();
+            analyser.fftSize = 128;
+            this.context.createMediaStreamSource(media).connect(analyser);
+            this.widget.visualize(analyser);
+            this.record(media);
+            this.widget.update(true, 'On air', 'Stop');
+        }
+        catch (error) {
+            this.stop();
+            this.widget.update(false, describe(error), 'Go live');
+        }
+    }
+    stop() {
+        this.active = false;
+        clearTimeout(this.timer);
+        this.recorder?.stop();
+        this.media?.getTracks().forEach(track => track.stop());
+        this.context?.close();
+        this.recorder = this.media = this.context = undefined;
+        this.widget.visualize();
+        this.widget.update(false, 'Off air', 'Go live');
+    }
+    destroy() {
+        this.stop();
+        this.widget.destroy();
+    }
+    record(media) {
+        const mimeType = MIME_TYPES.find(type => MediaRecorder.isTypeSupported(type));
+        if (!mimeType)
+            throw new Error('This browser cannot record Opus audio');
+        this.recorder = new MediaRecorder(media, { mimeType, audioBitsPerSecond: this.options.bitrate ?? 64_000 });
+        this.recorder.ondataavailable = event => this.publish(event.data);
+        this.recorder.start();
+        this.timer = setTimeout(() => {
+            this.recorder?.stop();
+            this.record(media);
+        }, (this.options.segmentSeconds ?? 2) * 1000);
+    }
+    async publish(blob) {
+        if (!blob.size)
+            return;
+        const index = this.index++;
+        try {
+            await this.swarm.publish(this.signer, this.topic, index, new Uint8Array(await blob.arrayBuffer()));
+            if (this.active)
+                this.widget.update(true, `On air · segment ${index}`, 'Stop');
+        }
+        catch (error) {
+            if (this.active)
+                this.widget.update(true, `Upload failed: ${describe(error)}`, 'Stop');
+        }
+    }
+}

package/dist/swarm.d.ts

@@ -0,0 +1,12 @@
+import { Signer } from './chunk.js';
+export declare const DEFAULT_GATEWAY = "https://bzz.limo";
+export declare class Swarm {
+    private readonly gateway;
+    private readonly stamp?;
+    constructor(gateway?: string, stamp?: string | undefined);
+    publish(signer: Signer, topic: Uint8Array, index: number, data: Uint8Array): Promise<void>;
+    latest(owner: string, topic: Uint8Array): Promise<number>;
+    segment(owner: string, topic: Uint8Array, index: number): Promise<ArrayBuffer>;
+    private post;
+    private request;
+}

package/dist/swarm.js

@@ -0,0 +1,42 @@
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { chunkAddress, feedIdentifier, rootChunk, socAddress } from './chunk.js';
+export const DEFAULT_GATEWAY = 'https://bzz.limo';
+export class Swarm {
+    gateway;
+    stamp;
+    constructor(gateway = DEFAULT_GATEWAY, stamp) {
+        this.gateway = gateway;
+        this.stamp = stamp;
+    }
+    async publish(signer, topic, index, data) {
+        await this.post('/bytes', data);
+        const chunk = rootChunk(data);
+        const identifier = feedIdentifier(topic, index);
+        const signature = signer.sign(identifier, chunk);
+        await this.post(`/soc/${signer.owner}/${bytesToHex(identifier)}?sig=${bytesToHex(signature)}`, chunk.data);
+    }
+    async latest(owner, topic) {
+        const response = await this.request(`/feeds/${owner}/${bytesToHex(topic)}`, { method: 'HEAD', cache: 'no-store' });
+        const index = parseInt(response.headers.get('swarm-feed-index') ?? '', 16);
+        if (Number.isNaN(index))
+            throw new Error('Feed index is not readable');
+        return index;
+    }
+    async segment(owner, topic, index) {
+        const soc = await this.request(`/chunks/${bytesToHex(socAddress(feedIdentifier(topic, index), owner))}`);
+        const root = chunkAddress(new Uint8Array(await soc.arrayBuffer()).subarray(97));
+        return (await this.request(`/bytes/${bytesToHex(root)}`)).arrayBuffer();
+    }
+    async post(path, body) {
+        const headers = { 'content-type': 'application/octet-stream', 'swarm-redundancy-level': '0' };
+        if (this.stamp)
+            headers['swarm-postage-batch-id'] = this.stamp;
+        return this.request(path, { method: 'POST', headers, body: body });
+    }
+    async request(path, init) {
+        const response = await fetch(this.gateway + path, init);
+        if (!response.ok)
+            throw new Error(`Swarm responded ${response.status} to ${path.split('?')[0]}`);
+        return response;
+    }
+}

package/dist/widget.d.ts

@@ -0,0 +1,22 @@
+export interface Theme {
+    background: string;
+    foreground: string;
+    muted: string;
+    accent: string;
+    font: string;
+    radius: string;
+}
+export declare const defaultTheme: Theme;
+export type Target = HTMLElement | string;
+export declare class Widget {
+    private readonly host;
+    private readonly root;
+    private readonly button;
+    private readonly status;
+    private readonly bars;
+    private frame;
+    constructor(target: Target, title: string, theme: Partial<Theme> | undefined, onToggle: () => void);
+    update(active: boolean, status: string, label: string): void;
+    visualize(analyser?: AnalyserNode): void;
+    destroy(): void;
+}

package/dist/widget.js

@@ -0,0 +1,75 @@
+export const defaultTheme = {
+    background: '#16161d',
+    foreground: '#f4f4f6',
+    muted: '#8b8b99',
+    accent: '#ff5c39',
+    font: 'system-ui, -apple-system, "Segoe UI", sans-serif',
+    radius: '16px',
+};
+const BARS = 24;
+const STYLE = `
+:host { display: block }
+.radio {
+  display: flex; align-items: center; gap: 16px; padding: 16px; box-sizing: border-box;
+  background: var(--background); color: var(--foreground); font-family: var(--font); border-radius: var(--radius);
+}
+button {
+  flex: none; width: 48px; height: 48px; border: none; border-radius: 50%; cursor: pointer;
+  background: var(--accent); display: grid; place-items: center; transition: transform .15s;
+}
+button:hover { transform: scale(1.06) }
+button::after { content: ''; width: 16px; height: 16px; background: var(--background); clip-path: polygon(20% 0, 100% 50%, 20% 100%) }
+.active button::after { clip-path: inset(10% round 2px) }
+.text { flex: 1; min-width: 0 }
+.title { font-weight: 600; white-space: nowrap; overflow: hidden; text-overflow: ellipsis }
+.status { margin-top: 2px; font-size: .85em; color: var(--muted); white-space: nowrap; overflow: hidden; text-overflow: ellipsis }
+.active .status::before { content: '● '; color: var(--accent) }
+.meter { flex: none; display: flex; align-items: center; gap: 2px; height: 32px }
+.meter span { width: 3px; height: 8%; border-radius: 2px; background: var(--accent); opacity: .85 }
+`;
+export class Widget {
+    host;
+    root;
+    button;
+    status;
+    bars;
+    frame = 0;
+    constructor(target, title, theme = {}, onToggle) {
+        const parent = typeof target === 'string' ? document.querySelector(target) : target;
+        if (!parent)
+            throw new Error(`Element not found: ${target}`);
+        this.host = parent.appendChild(document.createElement('div'));
+        for (const [key, value] of Object.entries({ ...defaultTheme, ...theme }))
+            this.host.style.setProperty(`--${key}`, value);
+        const shadow = this.host.attachShadow({ mode: 'open' });
+        shadow.innerHTML = `<style>${STYLE}</style>
+      <div class="radio"><button></button><div class="text"><div class="title"></div><div class="status"></div></div><div class="meter"></div></div>`;
+        this.root = shadow.querySelector('.radio');
+        this.status = shadow.querySelector('.status');
+        shadow.querySelector('.title').textContent = title;
+        this.button = shadow.querySelector('button');
+        this.button.onclick = onToggle;
+        const meter = shadow.querySelector('.meter');
+        this.bars = Array.from({ length: BARS }, () => meter.appendChild(document.createElement('span')));
+    }
+    update(active, status, label) {
+        this.root.classList.toggle('active', active);
+        this.status.textContent = status;
+        this.button.ariaLabel = label;
+    }
+    visualize(analyser) {
+        cancelAnimationFrame(this.frame);
+        const levels = new Uint8Array(analyser?.frequencyBinCount ?? 0);
+        const draw = () => {
+            analyser?.getByteFrequencyData(levels);
+            this.bars.forEach((bar, i) => (bar.style.height = `${8 + ((levels[i * 2] ?? 0) / 255) * 92}%`));
+            if (analyser)
+                this.frame = requestAnimationFrame(draw);
+        };
+        draw();
+    }
+    destroy() {
+        cancelAnimationFrame(this.frame);
+        this.host.remove();
+    }
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "web3-radio",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Live audio streaming on Swarm. Embeddable publisher and player.",
+  "keywords": [
+    "swarm",
+    "ethswarm",
+    "web3",
+    "radio",
+    "audio",
+    "streaming",
+    "opus"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "dev": "vite examples",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "publish:examples": "sh scripts/publish-examples.sh"
+  },
+  "dependencies": {
+    "@noble/curves": "^2.4.0",
+    "@noble/hashes": "^2.4.0"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "vite": "^8.3.3",
+    "vite-plugin-singlefile": "^2.3.3"
+  }
+}