@domicile-desktop/system-audio 0.0.0-alpha-a330bf5f3aae

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connor Prussin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,56 @@
+# @domicile-desktop/system-audio
+
+A shell's mixer: devices, streams, cards, volume, mute and level meters, read
+from PulseAudio or PipeWire through `pactl` and `parec`.
+
+- Runs them with `@domicile-desktop/sdk/system`'s `spawn` and `run`, in the C
+  locale. They must be on the compositor's `PATH`; the flake's wrapper adds
+  PulseAudio's.
+- Published to npm. Ships built JavaScript and `.d.ts` from `dist/`.
+
+## Usage
+
+```ts
+import { system } from "@domicile-desktop/sdk/system";
+import { soundServer } from "@domicile-desktop/system-audio/sound-server";
+
+const server = soundServer(system(domicile));
+const stop = server.watch((audio) => draw(audio));
+await server.setVolume(audio.outputs[0].id, 0.5);
+const meters = server.meters((levels) => drawLevels(levels));
+meters.meter(new Map([[id, audio.meters.get(id)]]));
+```
+
+- `watch` holds `pactl -f json subscribe` open and reports the whole state on
+  each settled burst of changes. Without a sound server it reports nothing,
+  logs once and retries every 5 s.
+- Requests resolve `Result<Asked, AudioError>`. They run one at a time; a
+  volume overtaken by a later one for the same id is skipped
+  (`Asked.Overtaken`).
+- Volumes are kept between 0 and 1.5 (pavucontrol's maximum); NaN is refused.
+  Ids not of the form `watch` reports are refused before `pactl` runs.
+- Meters run one `parec` per id and report peaks 20 times a second. Metering a
+  microphone records it: call `stop` when the meters are not shown.
+- The library's own meters, other mixers' meters and PipeWire filter streams
+  are left out of the stream lists.
+- While the desktop is locked, only `watch`, and `setVolume` and `setMuted` on
+  an output, work ([LOCK.md](/docs/LOCK.md)). Everything else fails with
+  `locked`.
+
+## Modules
+
+| Module | What it is |
+| --- | --- |
+| `./sound-server` | `soundServer(system)` and its types. |
+| `./audio` | `Audio` and its devices, streams, cards and `Meter`s. |
+| `./audio-error` | `AudioError`: why a request was refused. |
+| `./asked` | `Asked`: what became of a request. |
+
+## Test
+
+```sh
+bun run turbo test --filter @domicile-desktop/system-audio
+```
+
+Unit tests read recorded `pactl -f json` output (`src/pactl.fixture.ts`)
+through a fake `System` (`src/system.fixture.ts`).

package/dist/asked.d.ts

@@ -0,0 +1,6 @@
+/** What became of a mixer's request. */
+export declare enum Asked {
+    Done = 0,
+    /** Skipped: a later volume for the same id came first. */
+    Overtaken = 1
+}

package/dist/asked.js

@@ -0,0 +1,7 @@
+/** What became of a mixer's request. */
+export var Asked;
+(function (Asked) {
+    Asked[Asked["Done"] = 0] = "Done";
+    /** Skipped: a later volume for the same id came first. */
+    Asked[Asked["Overtaken"] = 1] = "Overtaken";
+})(Asked || (Asked = {}));

package/dist/audio-error.d.ts

@@ -0,0 +1,37 @@
+export declare enum AudioErrorKind {
+    /** A volume that is NaN or infinite. */
+    NotANumber = 0,
+    /** An id that must name a device and names a stream. */
+    NotADevice = 1,
+    /** A stream moved to a device of the other direction. */
+    Mismatched = 2,
+    /** An id `watchAudio` never reported. */
+    UnknownId = 3,
+    /** `pactl` could not run, or the sound server refused. */
+    Refused = 4
+}
+/** Why the sound server was not asked, or said no. */
+export declare const AudioError: {
+    Mismatched: (stream: string, device: string) => {
+        device: string;
+        kind: AudioErrorKind.Mismatched;
+        stream: string;
+    };
+    NotADevice: (id: string) => {
+        id: string;
+        kind: AudioErrorKind.NotADevice;
+    };
+    NotANumber: () => {
+        kind: AudioErrorKind.NotANumber;
+    };
+    /** `message` is `pactl`'s error output, or why it did not run. */
+    Refused: (message: string) => {
+        kind: AudioErrorKind.Refused;
+        message: string;
+    };
+    UnknownId: (id: string) => {
+        id: string;
+        kind: AudioErrorKind.UnknownId;
+    };
+};
+export type AudioError = ReturnType<(typeof AudioError)[keyof typeof AudioError]>;

package/dist/audio-error.js

@@ -0,0 +1,32 @@
+export var AudioErrorKind;
+(function (AudioErrorKind) {
+    /** A volume that is NaN or infinite. */
+    AudioErrorKind[AudioErrorKind["NotANumber"] = 0] = "NotANumber";
+    /** An id that must name a device and names a stream. */
+    AudioErrorKind[AudioErrorKind["NotADevice"] = 1] = "NotADevice";
+    /** A stream moved to a device of the other direction. */
+    AudioErrorKind[AudioErrorKind["Mismatched"] = 2] = "Mismatched";
+    /** An id `watchAudio` never reported. */
+    AudioErrorKind[AudioErrorKind["UnknownId"] = 3] = "UnknownId";
+    /** `pactl` could not run, or the sound server refused. */
+    AudioErrorKind[AudioErrorKind["Refused"] = 4] = "Refused";
+})(AudioErrorKind || (AudioErrorKind = {}));
+/** Why the sound server was not asked, or said no. */
+export const AudioError = {
+    Mismatched: (stream, device) => ({
+        device,
+        kind: AudioErrorKind.Mismatched,
+        stream,
+    }),
+    NotADevice: (id) => ({
+        id,
+        kind: AudioErrorKind.NotADevice,
+    }),
+    NotANumber: () => ({ kind: AudioErrorKind.NotANumber }),
+    /** `message` is `pactl`'s error output, or why it did not run. */
+    Refused: (message) => ({
+        kind: AudioErrorKind.Refused,
+        message,
+    }),
+    UnknownId: (id) => ({ id, kind: AudioErrorKind.UnknownId }),
+};

package/dist/audio.d.ts

@@ -0,0 +1,79 @@
+/** A port of a device, or a profile of a card: something to switch it to. */
+export type AudioChoice = {
+    /** What `setPort` and `setProfile` name it by. */
+    name: string;
+    description: string;
+    /**
+     * `false` for a port with an empty jack, or a profile that needs one. It can
+     * still be selected.
+     */
+    available: boolean;
+};
+/** An output (a sink) or an input (a source). */
+export type AudioDevice = {
+    id: string;
+    description: string;
+    /** The loudest channel's volume as a fraction of 100%. Can exceed 1. */
+    volume: number;
+    muted: boolean;
+    /** Whether new streams go to it. */
+    default: boolean;
+    /**
+     * Whether it is an output's monitor source, which records what the output
+     * plays. Always `false` for an output.
+     */
+    monitor: boolean;
+    /** E.g. speakers, headphones, line in. Often empty. */
+    ports: readonly AudioChoice[];
+    /** The {@link AudioChoice.name} of the port in use, if it has ports. */
+    port: string | undefined;
+};
+/** Something playing (a sink input) or recording (a source output). */
+export type AudioStream = {
+    id: string;
+    /** The application playing or recording it. */
+    application: string;
+    /** The stream title, if the application set one. */
+    title: string | undefined;
+    volume: number;
+    muted: boolean;
+    /** The {@link AudioDevice.id} it plays to or records from, if listed. */
+    device: string | undefined;
+};
+/** A sound card and its profiles, which select the enabled devices. */
+export type AudioCard = {
+    id: string;
+    description: string;
+    /** Sorted best first. */
+    profiles: readonly AudioChoice[];
+    /** The {@link AudioChoice.name} of the profile in use. */
+    profile: string | undefined;
+};
+export declare enum MeterKind {
+    /** A source by name: an input, or an output's monitor. */
+    Source = 0,
+    /** A playback stream by index, as pavucontrol meters one. */
+    Stream = 1
+}
+/** Where a level meter records from. */
+export declare const Meter: {
+    Source: (name: string) => {
+        kind: MeterKind.Source;
+        name: string;
+    };
+    Stream: (index: number) => {
+        index: number;
+        kind: MeterKind.Stream;
+    };
+};
+export type Meter = ReturnType<(typeof Meter)[keyof typeof Meter]>;
+/** Every output, input, stream and card. */
+export type Audio = {
+    outputs: readonly AudioDevice[];
+    inputs: readonly AudioDevice[];
+    playback: readonly AudioStream[];
+    recording: readonly AudioStream[];
+    cards: readonly AudioCard[];
+    /** Where each meterable device or stream id is metered from. */
+    meters: ReadonlyMap<string, Meter>;
+};

package/dist/audio.js

@@ -0,0 +1,17 @@
+// The sound server's state, as `watchAudio` reports it.
+//
+// Ids are opaque. A device id is `output:` or `input:` plus the device name,
+// which survives a server restart. A stream id is `playback:` or `recording:`
+// plus the stream index, which lasts as long as the stream.
+export var MeterKind;
+(function (MeterKind) {
+    /** A source by name: an input, or an output's monitor. */
+    MeterKind[MeterKind["Source"] = 0] = "Source";
+    /** A playback stream by index, as pavucontrol meters one. */
+    MeterKind[MeterKind["Stream"] = 1] = "Stream";
+})(MeterKind || (MeterKind = {}));
+/** Where a level meter records from. */
+export const Meter = {
+    Source: (name) => ({ kind: MeterKind.Source, name }),
+    Stream: (index) => ({ index, kind: MeterKind.Stream }),
+};

package/dist/ids.d.ts

@@ -0,0 +1,17 @@
+import type { Result } from "@cprussin/option-result";
+import { AudioError } from "./audio-error";
+export declare enum Target {
+    Output = 0,
+    Input = 1,
+    Playback = 2,
+    Recording = 3
+}
+export declare const targetId: (target: Target, key: string | number) => string;
+/**
+ * Splits an id into its target and key. A stream's key must be its index, or
+ * `pactl` would look it up as a name.
+ */
+export declare const parseId: (id: string) => Result<{
+    target: Target;
+    key: string;
+}, AudioError>;

package/dist/ids.js

@@ -0,0 +1,45 @@
+// The kinds of thing an id names, and the ids themselves: the kind's prefix,
+// a colon, then a device name or stream index.
+import { Err, Ok } from "@cprussin/option-result";
+import { AudioError } from "./audio-error";
+export var Target;
+(function (Target) {
+    Target[Target["Output"] = 0] = "Output";
+    Target[Target["Input"] = 1] = "Input";
+    Target[Target["Playback"] = 2] = "Playback";
+    Target[Target["Recording"] = 3] = "Recording";
+})(Target || (Target = {}));
+export const targetId = (target, key) => `${prefix(target)}:${key.toString()}`;
+/**
+ * Splits an id into its target and key. A stream's key must be its index, or
+ * `pactl` would look it up as a name.
+ */
+export const parseId = (id) => {
+    const colon = id.indexOf(":");
+    const target = TARGETS.find((candidate) => prefix(candidate) === id.slice(0, colon));
+    const key = id.slice(colon + 1);
+    return colon === -1 || target === undefined || !fits(target, key)
+        ? Err(AudioError.UnknownId(id))
+        : Ok({ key, target });
+};
+const TARGETS = [
+    Target.Output,
+    Target.Input,
+    Target.Playback,
+    Target.Recording,
+];
+const fits = (target, key) => target === Target.Playback || target === Target.Recording
+    ? /^\d+$/.test(key)
+    : key !== "";
+const prefix = (target) => {
+    switch (target) {
+        case Target.Output:
+            return "output";
+        case Target.Input:
+            return "input";
+        case Target.Playback:
+            return "playback";
+        case Target.Recording:
+            return "recording";
+    }
+};

package/dist/meters.d.ts

@@ -0,0 +1,3 @@
+import type { AudioSystem, Levels, Meters, Report } from "./sound-server";
+/** See `SoundServer.meters`. */
+export declare const meters: (system: AudioSystem, onLevels: (levels: Levels) => void, tickMs: number, report: Report) => Meters;

package/dist/meters.js

@@ -0,0 +1,120 @@
+// Level meters: one `parec` per metered id, sampled for its peak.
+//
+// `parec` cannot use the server's own peak detection, so it records 1000 mono
+// samples a second and the peak is taken here.
+import { MeterKind } from "./audio";
+import { C_LOCALE } from "./pactl";
+import { peak } from "./peak";
+import { METER_APPLICATION } from "./reading";
+/** High enough to catch transients, low enough to run one per device. */
+const RATE = 1000;
+/** See `SoundServer.meters`. */
+export const meters = (system, onLevels, tickMs, report) => {
+    const running = new Map();
+    const said = { cannotRecord: false };
+    const ticking = setInterval(() => {
+        const levels = levelsOf(running);
+        if (levels.size > 0) {
+            onLevels(levels);
+        }
+    }, tickMs);
+    return {
+        // A meter whose source changed restarts: a stream moved to another
+        // device keeps its id.
+        meter: (wanted) => {
+            for (const [id, recording] of running) {
+                const meter = wanted.get(id);
+                if (meter === undefined || !sameMeter(meter, recording.meter)) {
+                    stop(recording);
+                    running.delete(id);
+                }
+            }
+            for (const [id, meter] of wanted) {
+                if (!running.has(id)) {
+                    running.set(id, record(system, meter, report, said));
+                }
+            }
+        },
+        stop: () => {
+            clearInterval(ticking);
+            for (const recording of running.values()) {
+                stop(recording);
+            }
+            running.clear();
+        },
+    };
+};
+/** `parec` arguments to record `meter` as mono floats, named as a meter. */
+const argv = (meter) => [
+    "parec",
+    meter.kind === MeterKind.Source
+        ? `--device=${meter.name}`
+        : `--monitor-stream=${meter.index.toString()}`,
+    "--raw",
+    "--format=float32le",
+    "--channels=1",
+    `--rate=${RATE.toString()}`,
+    "--latency-msec=30",
+    `--property=application.id=${METER_APPLICATION}`,
+];
+/** Starts a `parec` for `meter`. One that cannot start stays silent. */
+const record = (system, meter, report, said) => {
+    const recording = {
+        loudest: undefined,
+        meter,
+        process: undefined,
+        stopped: false,
+    };
+    system
+        .spawn(argv(meter), C_LOCALE)
+        .then(async (started) => {
+        await started.match({
+            Err: (error) => {
+                if (!said.cannotRecord) {
+                    said.cannotRecord = true;
+                    report("the meters cannot record; they read nothing", error.message);
+                }
+                return Promise.resolve();
+            },
+            Ok: (process) => {
+                recording.process = process;
+                if (recording.stopped) {
+                    process.kill();
+                }
+                return listen(process.stdout, recording);
+            },
+        });
+    })
+        .catch((error) => {
+        // biome-ignore lint/suspicious/noConsole: a meter has no caller to return to
+        console.error("a level meter broke", error);
+    });
+    return recording;
+};
+/** Keeps `recording.loudest` at the loudest sample `samples` carried. */
+const listen = async (samples, recording) => {
+    let carried = new Uint8Array();
+    for await (const read of samples) {
+        const { loudest, rest } = peak(carried, read);
+        recording.loudest = Math.max(recording.loudest ?? 0, loudest);
+        carried = rest;
+    }
+};
+const stop = (recording) => {
+    recording.stopped = true;
+    recording.process?.kill();
+};
+/** Each meter's peak since the last call, resetting it. Silent ones are left out. */
+const levelsOf = (running) => new Map([...running].flatMap(([id, recording]) => {
+    const loudest = recording.loudest;
+    recording.loudest = loudest === undefined ? undefined : 0;
+    return loudest === undefined ? [] : [[id, loudest]];
+}));
+const sameMeter = (a, b) => {
+    switch (a.kind) {
+        case MeterKind.Source:
+            return b.kind === MeterKind.Source && a.name === b.name;
+        case MeterKind.Stream:
+            return b.kind === MeterKind.Stream && a.index === b.index;
+    }
+};

package/dist/pactl.d.ts

@@ -0,0 +1,14 @@
+import type { Result } from "@cprussin/option-result";
+import { AudioError } from "./audio-error";
+import type { AudioSystem } from "./sound-server";
+/**
+ * The C locale, because some of `pactl`'s JSON values are read as English
+ * words.
+ */
+export declare const C_LOCALE: {
+    env: {
+        LC_ALL: string;
+    };
+};
+/** Runs `pactl args` and returns its output, or its error output as the error. */
+export declare const pactl: (system: AudioSystem, args: readonly string[]) => Promise<Result<string, AudioError>>;

package/dist/pactl.js

@@ -0,0 +1,13 @@
+import { Err, Ok } from "@cprussin/option-result";
+import { AudioError } from "./audio-error";
+/**
+ * The C locale, because some of `pactl`'s JSON values are read as English
+ * words.
+ */
+export const C_LOCALE = { env: { LC_ALL: "C" } };
+/** Runs `pactl args` and returns its output, or its error output as the error. */
+export const pactl = async (system, args) => (await system.run(["pactl", ...args], C_LOCALE))
+    .mapErr((error) => AudioError.Refused(error.message))
+    .andThen((ran) => ran.code === 0
+    ? Ok(ran.stdout)
+    : Err(AudioError.Refused(ran.stderr.trim())));

package/dist/peak.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The loudest of the `f32` samples in `carried` then `read`, clipped to 1.
+ * `rest` is a trailing partial sample, to pass as `carried` with the next read.
+ */
+export declare const peak: (carried: Uint8Array, read: Uint8Array) => {
+    loudest: number;
+    rest: Uint8Array;
+};

package/dist/peak.js

@@ -0,0 +1,16 @@
+/** Bytes in one little-endian `f32` sample. */
+const SAMPLE = 4;
+/**
+ * The loudest of the `f32` samples in `carried` then `read`, clipped to 1.
+ * `rest` is a trailing partial sample, to pass as `carried` with the next read.
+ */
+export const peak = (carried, read) => {
+    const bytes = new Uint8Array([...carried, ...read]);
+    const whole = bytes.length - (bytes.length % SAMPLE);
+    const view = new DataView(bytes.buffer, 0, whole);
+    const samples = Array.from({ length: whole / SAMPLE }, (_, at) => Math.abs(view.getFloat32(at * SAMPLE, true)));
+    return {
+        loudest: Math.min(1, Math.max(0, ...samples)),
+        rest: bytes.slice(whole),
+    };
+};

package/dist/reading.d.ts

@@ -0,0 +1,8 @@
+import type { Result } from "@cprussin/option-result";
+import type { Audio } from "./audio";
+/** The raw volume `pactl` reports for 100%. */
+export declare const NORMAL = 65536;
+/** Application id of this library's meters, so they are hidden from the lists. */
+export declare const METER_APPLICATION = "org.domicile.meter";
+/** Parses the output of `pactl -f json info` and `pactl -f json list`. */
+export declare const reading: (info: string, list: string) => Result<Audio, string>;

package/dist/reading.js

@@ -0,0 +1,218 @@
+// Parses `pactl -f json info` and `pactl -f json list` into `Audio`.
+//
+// Run `pactl` under `LC_ALL=C`: it translates some values, such as a port's
+// availability, that this module matches as English words.
+import { Err, Ok } from "@cprussin/option-result";
+import { z } from "zod";
+import { Meter } from "./audio";
+import { Target, targetId } from "./ids";
+/** The raw volume `pactl` reports for 100%. */
+export const NORMAL = 65_536;
+/** Application id of this library's meters, so they are hidden from the lists. */
+export const METER_APPLICATION = "org.domicile.meter";
+/** Applications whose streams are level meters. Matches pavucontrol's list. */
+const MIXERS = new Set([
+    METER_APPLICATION,
+    "org.PulseAudio.pavucontrol",
+    "org.gnome.VolumeControl",
+    "org.kde.kmixd",
+]);
+/** PipeWire property shared by a filter's device and its stream. */
+const LINK_GROUP = "node.link-group";
+/** Parses the output of `pactl -f json info` and `pactl -f json list`. */
+export const reading = (info, list) => {
+    const parsedInfo = parseJson(infoSchema, info);
+    const parsedList = parseJson(listSchema, list);
+    return parsedInfo.andThen((server) => parsedList.map((devices) => audioOf(server, devices)));
+};
+const volumeSchema = z.record(z.string(), z.unknown());
+const propertiesSchema = z.record(z.string(), z.string()).default({});
+const infoSchema = z.object({
+    default_sink_name: z.string().nullish(),
+    default_source_name: z.string().nullish(),
+});
+const deviceSchema = z.object({
+    active_port: z.string().nullish(),
+    description: z.string().nullish(),
+    index: z.number(),
+    /** On a source, the sink it monitors; on a sink, its monitor source. */
+    monitor_source: z.string().nullish(),
+    mute: z.boolean(),
+    name: z.string(),
+    ports: z
+        .array(z.object({
+        availability: z.string(),
+        description: z.string(),
+        name: z.string(),
+    }))
+        .default([]),
+    properties: propertiesSchema,
+    volume: volumeSchema,
+});
+const streamSchema = z.object({
+    index: z.number(),
+    mute: z.boolean(),
+    properties: propertiesSchema,
+    /** A sink input's device. */
+    sink: z.number().optional(),
+    /** A source output's device. */
+    source: z.number().optional(),
+    volume: volumeSchema,
+});
+const cardSchema = z.object({
+    active_profile: z.string().nullish(),
+    name: z.string(),
+    profiles: z.record(z.string(), z.object({
+        available: z.boolean(),
+        description: z.string(),
+        priority: z.number().default(0),
+    })),
+    properties: propertiesSchema,
+});
+const listSchema = z.object({
+    cards: z.array(cardSchema).default([]),
+    sink_inputs: z.array(streamSchema).default([]),
+    sinks: z.array(deviceSchema).default([]),
+    source_outputs: z.array(streamSchema).default([]),
+    sources: z.array(deviceSchema).default([]),
+});
+const parseJson = (schema, text) => {
+    const json = z.string().transform(jsonOf).pipe(schema).safeParse(text);
+    return json.success ? Ok(json.data) : Err(z.prettifyError(json.error));
+};
+const jsonOf = (text, context) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        context.addIssue({ code: "custom", input: text, message: "not JSON" });
+        return z.NEVER;
+    }
+};
+const audioOf = (info, list) => {
+    const outputsByIndex = new Map(list.sinks.map((sink) => [sink.index, targetId(Target.Output, sink.name)]));
+    const inputsByIndex = new Map(list.sources.map((source) => [
+        source.index,
+        targetId(Target.Input, source.name),
+    ]));
+    const plumbing = new Set([...list.sinks, ...list.sources].flatMap((device) => {
+        const group = device.properties[LINK_GROUP];
+        return group === undefined ? [] : [group];
+    }));
+    const listed = (stream) => !isAMixers(stream) && !isPlumbing(stream, plumbing);
+    return {
+        cards: list.cards.map(card),
+        inputs: list.sources.map((source) => device(source, Target.Input, info.default_source_name)),
+        meters: meters(list),
+        outputs: list.sinks.map((sink) => device(sink, Target.Output, info.default_sink_name)),
+        playback: list.sink_inputs
+            .filter(listed)
+            .map((playing) => stream(playing, Target.Playback, outputsByIndex.get(playing.sink ?? -1))),
+        recording: list.source_outputs
+            .filter(listed)
+            .map((recording) => stream(recording, Target.Recording, inputsByIndex.get(recording.source ?? -1))),
+    };
+};
+/** An output's monitor source (if any), an input itself, or a stream. */
+const meters = (list) => new Map([
+    ...list.sinks.flatMap((sink) => sink.monitor_source === undefined || sink.monitor_source === null
+        ? []
+        : [
+            [
+                targetId(Target.Output, sink.name),
+                Meter.Source(sink.monitor_source),
+            ],
+        ]),
+    ...list.sources.map((source) => [
+        targetId(Target.Input, source.name),
+        Meter.Source(source.name),
+    ]),
+    ...list.sink_inputs.map((playing) => [
+        targetId(Target.Playback, playing.index),
+        Meter.Stream(playing.index),
+    ]),
+]);
+const device = (from, kind, defaultName) => ({
+    default: defaultName === from.name,
+    description: from.description ?? from.name,
+    id: targetId(kind, from.name),
+    monitor: kind === Target.Input && isAMonitor(from),
+    muted: from.mute,
+    port: from.active_port ?? undefined,
+    ports: from.ports.map((port) => ({
+        available: port.availability !== "not available",
+        description: port.description,
+        name: port.name,
+    })),
+    volume: loudest(from.volume),
+});
+/**
+ * Whether a source monitors a sink. Uses `device.class` when the server sets
+ * it, else whether `monitor_source` names a sink. Some `pactl` versions write
+ * "none" there as `""` or `"n/a"`.
+ */
+const isAMonitor = (source) => {
+    const deviceClass = source.properties["device.class"];
+    return deviceClass === undefined
+        ? namesASink(source.monitor_source)
+        : deviceClass === "monitor";
+};
+const namesASink = (sink) => sink !== undefined && sink !== null && sink !== "" && sink !== "n/a";
+/**
+ * Uses the application name with the media name as title. Without an
+ * application name, the media name becomes the name and there is no title.
+ */
+const stream = (from, kind, device) => {
+    const media = from.properties["media.name"];
+    const application = from.properties["application.name"];
+    return {
+        application: application ?? media ?? "Unknown",
+        device,
+        id: targetId(kind, from.index),
+        muted: from.mute,
+        title: application === undefined ? undefined : media,
+        volume: loudest(from.volume),
+    };
+};
+const isAMixers = (stream) => {
+    const application = stream.properties["application.id"];
+    return application !== undefined && MIXERS.has(application);
+};
+/**
+ * Whether a stream carries a filter device's audio to the hardware, such as a
+ * PipeWire filter-chain for speaker correction. It shares the device's link
+ * group.
+ */
+const isPlumbing = (stream, plumbing) => {
+    const group = stream.properties[LINK_GROUP];
+    return group !== undefined && plumbing.has(group);
+};
+const card = (from) => ({
+    description: from.properties["device.description"] ?? from.name,
+    id: from.name,
+    profile: from.active_profile ?? undefined,
+    profiles: Object.entries(from.profiles)
+        .toSorted(([aName, a], [bName, b]) => b.priority - a.priority || byCodeUnits(aName, bName))
+        .map(([name, profile]) => ({
+        available: profile.available,
+        description: profile.description,
+        name,
+    })),
+});
+/**
+ * The loudest channel as a fraction of 100%. An invalid volume, reported as
+ * `{"error": ...}`, reads as 0.
+ */
+const loudest = (volume) => Math.max(0, ...Object.values(volume).flatMap((channel) => {
+    const parsed = channelSchema.safeParse(channel);
+    return parsed.success ? [parsed.data.value / NORMAL] : [];
+}));
+const channelSchema = z.object({ value: z.number() });
+const byCodeUnits = (a, b) => {
+    if (a < b) {
+        return -1;
+    }
+    else {
+        return a > b ? 1 : 0;
+    }
+};

package/dist/request-queue.d.ts

@@ -0,0 +1,10 @@
+import type { Result } from "@cprussin/option-result";
+import { Asked } from "./asked";
+import type { AudioError } from "./audio-error";
+import type { Request } from "./request";
+import type { AudioSystem } from "./sound-server";
+/**
+ * Runs requests one at a time, in order. Requests that wait while another
+ * runs are coalesced: see {@link coalesce}.
+ */
+export declare const requestQueue: (system: AudioSystem) => (request: Request) => Promise<Result<Asked, AudioError>>;

package/dist/request-queue.js

@@ -0,0 +1,38 @@
+import { Err, Ok } from "@cprussin/option-result";
+import { Asked } from "./asked";
+import { pactl } from "./pactl";
+import { argv, coalesce } from "./request";
+/**
+ * Runs requests one at a time, in order. Requests that wait while another
+ * runs are coalesced: see {@link coalesce}.
+ */
+export const requestQueue = (system) => {
+    const waiting = [];
+    const state = { running: false };
+    return (request) => argv(request).match({
+        Err: (error) => Promise.resolve(Err(error)),
+        Ok: (args) => new Promise((answer) => {
+            waiting.push({ answer, args, request });
+            if (!state.running) {
+                state.running = true;
+                drain(system, waiting, state).catch((error) => {
+                    // biome-ignore lint/suspicious/noConsole: no caller is waiting on the queue itself
+                    console.error("the mixer's request queue broke", error);
+                });
+            }
+        }),
+    });
+};
+/** Runs what is waiting, then marks the queue idle in the same turn. */
+const drain = async (system, waiting, state) => {
+    while (waiting.length > 0) {
+        const batch = waiting.splice(0);
+        const kept = coalesce(batch.map(({ request }) => request));
+        for (const { answer, args, request } of batch) {
+            answer(kept.includes(request)
+                ? (await pactl(system, args)).map(() => Asked.Done)
+                : Ok(Asked.Overtaken));
+        }
+    }
+    state.running = false;
+};

package/dist/request.d.ts

@@ -0,0 +1,53 @@
+import type { Result } from "@cprussin/option-result";
+import { AudioError } from "./audio-error";
+export declare enum RequestKind {
+    Volume = 0,
+    Muted = 1,
+    Default = 2,
+    Move = 3,
+    Port = 4,
+    Profile = 5
+}
+export declare const Request: {
+    Default: (id: string) => {
+        id: string;
+        kind: RequestKind.Default;
+    };
+    Move: (id: string, device: string) => {
+        device: string;
+        id: string;
+        kind: RequestKind.Move;
+    };
+    Muted: (id: string, muted: boolean) => {
+        id: string;
+        kind: RequestKind.Muted;
+        muted: boolean;
+    };
+    Port: (id: string, port: string) => {
+        id: string;
+        kind: RequestKind.Port;
+        port: string;
+    };
+    Profile: (card: string, profile: string) => {
+        card: string;
+        kind: RequestKind.Profile;
+        profile: string;
+    };
+    Volume: (id: string, volume: number) => {
+        id: string;
+        kind: RequestKind.Volume;
+        volume: number;
+    };
+};
+export type Request = ReturnType<(typeof Request)[keyof typeof Request]>;
+/**
+ * `pactl` arguments for `request`. They start with `--` so a name cannot be
+ * read as an option.
+ */
+export declare const argv: (request: Request) => Result<string[], AudioError>;
+/**
+ * Drops each volume request whose next request for the same target is also a
+ * volume. A dragged slider sends many requests a second; only the last
+ * matters.
+ */
+export declare const coalesce: (requests: readonly Request[]) => Request[];

package/dist/request.js

@@ -0,0 +1,127 @@
+// What a mixer asks the sound server, and the `pactl` arguments for it.
+import { Err, Ok } from "@cprussin/option-result";
+import { AudioError } from "./audio-error";
+import { parseId, Target } from "./ids";
+import { NORMAL } from "./reading";
+/** The highest volume a mixer may set: 150%, matching pavucontrol. */
+const CEILING = 1.5;
+export var RequestKind;
+(function (RequestKind) {
+    RequestKind[RequestKind["Volume"] = 0] = "Volume";
+    RequestKind[RequestKind["Muted"] = 1] = "Muted";
+    RequestKind[RequestKind["Default"] = 2] = "Default";
+    RequestKind[RequestKind["Move"] = 3] = "Move";
+    RequestKind[RequestKind["Port"] = 4] = "Port";
+    RequestKind[RequestKind["Profile"] = 5] = "Profile";
+})(RequestKind || (RequestKind = {}));
+export const Request = {
+    Default: (id) => ({ id, kind: RequestKind.Default }),
+    Move: (id, device) => ({
+        device,
+        id,
+        kind: RequestKind.Move,
+    }),
+    Muted: (id, muted) => ({
+        id,
+        kind: RequestKind.Muted,
+        muted,
+    }),
+    Port: (id, port) => ({
+        id,
+        kind: RequestKind.Port,
+        port,
+    }),
+    Profile: (card, profile) => ({
+        card,
+        kind: RequestKind.Profile,
+        profile,
+    }),
+    Volume: (id, volume) => ({
+        id,
+        kind: RequestKind.Volume,
+        volume,
+    }),
+};
+/**
+ * `pactl` arguments for `request`. They start with `--` so a name cannot be
+ * read as an option.
+ */
+export const argv = (request) => words(request).map((args) => ["--", ...args]);
+/**
+ * Drops each volume request whose next request for the same target is also a
+ * volume. A dragged slider sends many requests a second; only the last
+ * matters.
+ */
+export const coalesce = (requests) => requests.filter((request, at) => {
+    const next = requests
+        .slice(at + 1)
+        .find((later) => subject(later) === subject(request));
+    return !(request.kind === RequestKind.Volume && next?.kind === RequestKind.Volume);
+});
+const words = (request) => {
+    switch (request.kind) {
+        case RequestKind.Volume:
+            return rawVolume(request.volume).andThen((raw) => parseId(request.id).map(({ key, target }) => [
+                `set-${noun(target)}-volume`,
+                key,
+                raw.toString(),
+            ]));
+        case RequestKind.Muted:
+            return parseId(request.id).map(({ key, target }) => [
+                `set-${noun(target)}-mute`,
+                key,
+                request.muted ? "1" : "0",
+            ]);
+        case RequestKind.Default:
+            return device(request.id).map(({ key, target }) => [
+                `set-default-${noun(target)}`,
+                key,
+            ]);
+        case RequestKind.Move:
+            return parseId(request.id).andThen((stream) => device(request.device).andThen((to) => moveVerb(stream.target, to.target).match({
+                Err: () => Err(AudioError.Mismatched(request.id, request.device)),
+                Ok: (verb) => Ok([verb, stream.key, to.key]),
+            })));
+        case RequestKind.Port:
+            return device(request.id).map(({ key, target }) => [
+                `set-${noun(target)}-port`,
+                key,
+                request.port,
+            ]);
+        case RequestKind.Profile:
+            return Ok(["set-card-profile", request.card, request.profile]);
+    }
+};
+/** The id or card a request is about, for {@link coalesce}. */
+const subject = (request) => request.kind === RequestKind.Profile ? request.card : request.id;
+const rawVolume = (volume) => Number.isFinite(volume)
+    ? Ok(Math.round(Math.min(Math.max(volume, 0), CEILING) * NORMAL))
+    : Err(AudioError.NotANumber());
+/** Parses an id that must name a device. */
+const device = (id) => parseId(id).andThen((parsed) => parsed.target === Target.Output || parsed.target === Target.Input
+    ? Ok(parsed)
+    : Err(AudioError.NotADevice(id)));
+const moveVerb = (stream, device) => {
+    if (stream === Target.Playback && device === Target.Output) {
+        return Ok("move-sink-input");
+    }
+    else if (stream === Target.Recording && device === Target.Input) {
+        return Ok("move-source-output");
+    }
+    else {
+        return Err("mismatched");
+    }
+};
+/** The `pactl` name for a target. */
+const noun = (target) => {
+    switch (target) {
+        case Target.Output:
+            return "sink";
+        case Target.Input:
+            return "source";
+        case Target.Playback:
+            return "sink-input";
+        case Target.Recording:
+            return "source-output";
+    }
+};

package/dist/sound-server.d.ts

@@ -0,0 +1,47 @@
+import type { Result } from "@cprussin/option-result";
+import type { System } from "@domicile-desktop/sdk/system";
+import type { Asked } from "./asked";
+import type { Audio, Meter } from "./audio";
+import type { AudioError } from "./audio-error";
+/** The system calls this library uses. */
+export type AudioSystem = Pick<System, "run" | "spawn">;
+/** Each meter's loudest sample since the last report, 0 through 1, by id. */
+export type Levels = ReadonlyMap<string, number>;
+/** Running meters. Metering a microphone records it: stop when not shown. */
+export type Meters = {
+    /** Meter these ids from these sources, and stop metering the rest. */
+    meter: (wanted: ReadonlyMap<string, Meter>) => void;
+    stop: () => void;
+};
+/** Ids come from {@link SoundServer.watch}; volumes are fractions of 100%. */
+export type SoundServer = {
+    /**
+     * Calls `onAudio` with the server's state and again after each change.
+     * Never calls it without a sound server. Returns a stop function.
+     */
+    watch: (onAudio: (audio: Audio) => void) => () => void;
+    /** Kept between 0 and 1.5, pavucontrol's maximum. */
+    setVolume: (id: string, volume: number) => Promise<Result<Asked, AudioError>>;
+    setMuted: (id: string, muted: boolean) => Promise<Result<Asked, AudioError>>;
+    /** Make a device the default for new streams. */
+    setDefault: (id: string) => Promise<Result<Asked, AudioError>>;
+    /** Move a stream to a device of its own direction. */
+    moveStream: (id: string, device: string) => Promise<Result<Asked, AudioError>>;
+    setPort: (id: string, port: string) => Promise<Result<Asked, AudioError>>;
+    setProfile: (card: string, profile: string) => Promise<Result<Asked, AudioError>>;
+    /** Level meters, reported to `onLevels` while any is running. */
+    meters: (onLevels: (levels: Levels) => void) => Meters;
+};
+/** How long to wait; shortened by tests. */
+export type Timing = {
+    /** Quiet after a change before the server is read again. */
+    settleMs: number;
+    /** Delay before subscribing again after a subscription ends. */
+    reopenMs: number;
+    /** Interval between meter reports. */
+    tickMs: number;
+};
+/** Says that something keeps failing in the background. */
+export type Report = (message: string, detail: unknown) => void;
+/** The sound server, reached through `system`. */
+export declare const soundServer: (system: AudioSystem, timing?: Timing, report?: Report) => SoundServer;

package/dist/sound-server.js

@@ -0,0 +1,30 @@
+// The sound server (PulseAudio or PipeWire) for a shell's mixer, through
+// `pactl` and `parec` run by `@domicile-desktop/sdk/system`.
+//
+// - `pactl` and `parec` work with both PulseAudio and `pipewire-pulse`. The
+//   compositor's `PATH` must have them.
+// - Requests run one at a time, in order, so the last volume a slider sent is
+//   the one the server keeps.
+import { meters } from "./meters";
+import { Request } from "./request";
+import { requestQueue } from "./request-queue";
+import { watchAudio } from "./watch-audio";
+const TIMING = { reopenMs: 5000, settleMs: 30, tickMs: 50 };
+/** The sound server, reached through `system`. */
+export const soundServer = (system, timing = TIMING, report = warn) => {
+    const ask = requestQueue(system);
+    return {
+        meters: (onLevels) => meters(system, onLevels, timing.tickMs, report),
+        moveStream: (id, device) => ask(Request.Move(id, device)),
+        setDefault: (id) => ask(Request.Default(id)),
+        setMuted: (id, muted) => ask(Request.Muted(id, muted)),
+        setPort: (id, port) => ask(Request.Port(id, port)),
+        setProfile: (card, profile) => ask(Request.Profile(card, profile)),
+        setVolume: (id, volume) => ask(Request.Volume(id, volume)),
+        watch: (onAudio) => watchAudio(system, onAudio, timing, report),
+    };
+};
+const warn = (message, detail) => {
+    // biome-ignore lint/suspicious/noConsole: background failures have no caller to return to
+    console.warn(message, detail);
+};

package/dist/subscription.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether a `pactl -f json subscribe` line means mixer state changed. Throws
+ * on a line that is not an event.
+ */
+export declare const announcesAChange: (line: string) => boolean;

package/dist/subscription.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/**
+ * `pactl subscribe` facilities that change mixer state. Client events are
+ * left out: `pactl list` is itself a client, so rereading on them would loop.
+ */
+const NEWS = new Set([
+    "sink",
+    "source",
+    "sink-input",
+    "source-output",
+    "card",
+    "server",
+]);
+/**
+ * Whether a `pactl -f json subscribe` line means mixer state changed. Throws
+ * on a line that is not an event.
+ */
+export const announcesAChange = (line) => NEWS.has(eventSchema.parse(JSON.parse(line)).on);
+const eventSchema = z.object({ on: z.string() });

package/dist/watch-audio.d.ts

@@ -0,0 +1,4 @@
+import type { Audio } from "./audio";
+import type { AudioSystem, Report, Timing } from "./sound-server";
+/** See `SoundServer.watch`. */
+export declare const watchAudio: (system: AudioSystem, onAudio: (audio: Audio) => void, timing: Timing, report: Report) => (() => void);

package/dist/watch-audio.js

@@ -0,0 +1,118 @@
+// Holds `pactl subscribe` open and reads the server again after each burst of
+// changes settles, subscribing again when the subscription ends.
+import { AudioError } from "./audio-error";
+import { C_LOCALE, pactl } from "./pactl";
+import { reading } from "./reading";
+import { announcesAChange } from "./subscription";
+const SUBSCRIBE = ["pactl", "-f", "json", "subscribe"];
+/** See `SoundServer.watch`. */
+export const watchAudio = (system, onAudio, timing, report) => {
+    const stopping = new AbortController();
+    const told = (audio) => {
+        if (!stopping.signal.aborted) {
+            onAudio(audio);
+        }
+    };
+    keepSubscribed(system, told, timing, report, stopping.signal).catch((error) => {
+        // biome-ignore lint/suspicious/noConsole: a broken watch has no caller to return to
+        console.error("the sound server watch broke", error);
+    });
+    return () => {
+        stopping.abort();
+    };
+};
+/** Subscribes until stopped, saying once if there is no sound server. */
+const keepSubscribed = async (system, onAudio, timing, report, signal) => {
+    let said = false;
+    while (!signal.aborted) {
+        const ended = await subscribe(system, onAudio, timing, report, signal);
+        if (!said) {
+            said = ended.match({
+                Err: (error) => {
+                    report("no sound server to read; the mixer is empty until there is", error);
+                    return true;
+                },
+                Ok: () => false,
+            });
+        }
+        await sleep(timing.reopenMs, signal);
+    }
+};
+/**
+ * One subscription: reads the server, then again after each settled burst of
+ * changes, until `pactl` exits. Fails if the first read does.
+ */
+const subscribe = async (system, onAudio, timing, report, signal) => (await system.spawn(SUBSCRIBE, C_LOCALE))
+    .mapErr((error) => AudioError.Refused(error.message))
+    .andThenAsync(async (subscription) => {
+    const kill = () => {
+        subscription.kill();
+    };
+    signal.addEventListener("abort", kill);
+    const settling = {
+        reads: Promise.resolve(),
+        timer: undefined,
+    };
+    const changed = () => {
+        clearTimeout(settling.timer);
+        settling.timer = setTimeout(() => {
+            settling.reads = settling.reads.then(async () => {
+                (await readServer(system)).match({
+                    Err: (error) => {
+                        report("the sound server could not be read", error);
+                    },
+                    Ok: onAudio,
+                });
+            });
+        }, timing.settleMs);
+    };
+    // Read after subscribing, so no change in between is missed.
+    const first = await readServer(system);
+    first.match({
+        // Returned below, once the subscription ends.
+        Err: () => undefined,
+        Ok: onAudio,
+    });
+    await forEachLine(subscription.stdout, (line) => {
+        if (announcesAChange(line)) {
+            changed();
+        }
+    });
+    await subscription.exited;
+    clearTimeout(settling.timer);
+    await settling.reads;
+    signal.removeEventListener("abort", kill);
+    return first.map(() => "ended");
+});
+const readServer = async (system) => {
+    const info = await pactl(system, ["-f", "json", "info"]);
+    const list = await pactl(system, ["-f", "json", "list"]);
+    return info.andThen((server) => list.map((devices) => parsed(server, devices)));
+};
+/** Throws on output that is not `pactl`'s JSON: a format this does not know. */
+const parsed = (info, list) => reading(info, list).match({
+    Err: (why) => {
+        throw new Error(`unreadable pactl JSON: ${why}`);
+    },
+    Ok: (audio) => audio,
+});
+const forEachLine = async (stream, onLine) => {
+    const decoder = new TextDecoder();
+    let carried = "";
+    for await (const bytes of stream) {
+        const text = decoder.decode(bytes, { stream: true });
+        const lines = (carried + text).split("\n");
+        carried = lines.slice(-1).join("");
+        for (const line of lines.slice(0, -1)) {
+            onLine(line);
+        }
+    }
+};
+/** Resolves after `ms`, or at once when `signal` aborts. */
+const sleep = (ms, signal) => new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal.addEventListener("abort", () => {
+        clearTimeout(timer);
+        resolve();
+    });
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "dependencies": {
+    "@cprussin/option-result": "^2.0.1",
+    "@domicile-desktop/sdk": "0.0.0-alpha-a330bf5f3aae",
+    "zod": "^4.5.4"
+  },
+  "description": "Volume, mute, devices, streams and level meters for a Domicile shell, through pactl and parec.",
+  "devDependencies": {
+    "@cprussin/tsconfig": "^5.0.0",
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  },
+  "exports": {
+    "./asked": {
+      "types": "./dist/asked.d.ts",
+      "default": "./dist/asked.js"
+    },
+    "./audio": {
+      "types": "./dist/audio.d.ts",
+      "default": "./dist/audio.js"
+    },
+    "./audio-error": {
+      "types": "./dist/audio-error.d.ts",
+      "default": "./dist/audio-error.js"
+    },
+    "./sound-server": {
+      "types": "./dist/sound-server.d.ts",
+      "default": "./dist/sound-server.js"
+    }
+  },
+  "files": [
+    "dist/**"
+  ],
+  "license": "MIT",
+  "name": "@domicile-desktop/system-audio",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test:types": "tsc --noEmit",
+    "test:unit": "bun test"
+  },
+  "type": "module",
+  "version": "0.0.0-alpha-a330bf5f3aae",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cprussin/domicile.git",
+    "directory": "packages/system-audio"
+  }
+}