@lox-audioserver/node-airplay-sender 0.4.0

package/README.md

@@ -0,0 +1,93 @@
+# @lox-audioserver/node-airplay-sender
+
+AirPlay sender for RAOP/AirPlay 1 with AirPlay 2 control/auth support. Best-effort AP2 audio (encryption path not validated against native code). Implements RTSP/UDP pipeline, ALAC encoding, and metadata handling with no native dependencies.
+
+## Requirements
+- Node.js 18+
+- PCM input: 16-bit little-endian, stereo, 44.1kHz (ALAC encoding is handled internally)
+
+## Installation
+```bash
+npm install lox-airplay-sender
+```
+
+## Quick start
+```ts
+import { start } from "lox-airplay-sender";
+
+const sender = start(
+  {
+    host: "192.168.1.162",
+    port: 7000,          // defaults to 5000
+    airplay2: true,      // set to true for AirPlay 2 devices
+    log: (level, msg, data) => console.log(`[${level}]`, msg, data),
+  },
+  (event) => console.log("event", event)
+);
+
+sender.setMetadata({
+  title: "Track",
+  artist: "Artist",
+  album: "Album",
+  coverUrl: "https://example.com/cover.jpg",
+  durationMs: 180_000,
+  elapsedMs: 0,
+});
+
+// Write raw PCM chunks as they arrive
+sender.sendPcm(Buffer.from(/* pcm data */));
+```
+
+## API
+### `start(options, onEvent?) => LoxAirplaySender`
+Creates and starts a sender for one AirPlay device. Returns the instance so you can call methods directly.
+
+**Options**
+- `host` (string, required) AirPlay device hostname/IP.
+- `port` (number) RAOP port, default 5000.
+- `name` (string) Sender name shown on receiver.
+- `password` (string | null) AirPlay 1 password.
+- `volume` (number) Initial volume (0–100), default 50.
+- `mode` (number) RAOP mode; defaults to 2 when `airplay2` is true, else 0.
+- `txt` (string[]) Custom TXT records.
+- `forceAlac` (boolean) Encode ALAC even when input is ALAC; default true.
+- `alacEncoding` (boolean) Enable ALAC encoding; default true.
+- `inputCodec` (`"pcm"` | `"alac"`) Defaults to `"pcm"`.
+- `airplay2` (boolean) Enable AirPlay 2 auth/flags; default false.
+- `startTimeMs` (number) Unix ms to align playback across devices.
+- `startTimeNtp` (bigint | number | `{ sec, frac }`) Absolute NTP start time (sec<<32|frac) for tighter sync.
+- `deviceMagic` (number) Override per-session SSRC/device ID used in RTP/RTCP.
+- `resendBufferSize` (number) Override resend cache size (packets); defaults to 1000.
+- `underrunMuteMs` (number) Mute window in ms after an underrun to smooth recovery; defaults to 50.
+- `sendRtcpXr` (boolean) Emit RTCP Extended Reports (RRT) alongside sync/SSR; default false.
+- `debugDump` (boolean) Log RTSP/RTCP traffic for debugging; default false.
+- `debug` (boolean) Verbose logging from the transport stack.
+- `log` `(level, message, data?) => void` Hook for library logs.
+- `config` (partial) Override buffer/sync/RTSP tuning at runtime (see `src/utils/config.ts` for keys like `packets_in_buffer`, `stream_latency`, `sync_period`, retry/backoff, etc.).
+
+**Events** (sent to `onEvent` callback)
+- `device`: `{ event: "device", message: status, detail: { key, desc } }`
+- `buffer`: `{ event: "buffer", message: status }` where status is `buffering|playing|drain|end`
+- `error`: `{ event: "error", message }`
+- `metrics`: `{ event: "metrics", detail }` sync drift snapshots emitted on each sync tick when enabled.
+
+### `LoxAirplaySender` methods
+- `sendPcm(chunk: Buffer)`: Push raw PCM audio. If `inputCodec` is `"alac"` you can push ALAC frames.
+- `pipeStream(stream: Readable)`: Convenience to pipe a Node stream into `sendPcm`; auto-stops on `end`/`error`.
+- `setMetadata({ title, artist, album, cover, coverUrl, elapsedMs, durationMs })`: Updates track info, cover art (Buffer or URL), and progress. Cover URLs are fetched with a short timeout and deduplicated.
+- `setTrackInfo(title, artist?, album?)`: Direct track update.
+- `setArtwork(buffer, mime?)`: Send cover art immediately.
+- `setProgress(elapsedSec, durationSec)`: Manual progress update.
+- `setVolume(volume)`: Adjust volume (0–100).
+- `setPasscode(passcode)`: Provide a passcode when the receiver requests it.
+- `stop()`: Stop the sender, close sockets/streams, and clear state.
+
+## Sync playback
+Use `startTimeMs` to align multiple senders to the same start clock (Unix ms). Feed each sender PCM in lockstep; they will start at the scheduled time.
+
+## Development
+```bash
+npm install
+npm run build
+npm run clean   # remove dist
+```

package/dist/core/ap2_test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/ap2_test.js

@@ -0,0 +1,8 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const number_1 = __importDefault(require("../homekit/number"));
+const u = number_1.default.UInt16toBufferBE(287);
+console.log(Buffer.concat([u.slice(1), u.slice(0, 1)]));

package/dist/core/atv.d.ts

@@ -0,0 +1,16 @@
+import httpClientFactory from '../utils/http';
+declare class ATV {
+    addr: string;
+    port: number;
+    httpClient: ReturnType<typeof httpClientFactory>;
+    auth_secret: string | null;
+    constructor(addr: string, port?: number);
+    auth(configFilePath: string, authenticator: () => Promise<string>): Promise<import("../utils/http").MessageObject | null>;
+    authSecret(): string | null;
+    authSimple(authenticator: () => Promise<string>): Promise<void>;
+    verifySimple(secret: string): Promise<import("../utils/http").MessageObject | null>;
+    play(videoUrl: string): Promise<import("../utils/http").MessageObject | null>;
+    stop(): Promise<import("../utils/http").MessageObject | null>;
+    close(): void;
+}
+export default ATV;

package/dist/core/atv.js

@@ -0,0 +1,215 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const crypto_1 = __importDefault(require("crypto"));
+const fs_1 = __importDefault(require("fs"));
+const bplist_creator_1 = __importDefault(require("bplist-creator"));
+const bplist_parser_1 = __importDefault(require("bplist-parser"));
+const srp_1 = __importDefault(require("./srp"));
+const atvAuthenticator_1 = __importDefault(require("./atvAuthenticator"));
+const http_1 = __importDefault(require("../utils/http"));
+// ...
+// Configuration.
+const loadConfig = (configFilePath) => !fs_1.default.existsSync(configFilePath) ? null : JSON.parse(fs_1.default.readFileSync(configFilePath, 'utf8'));
+const saveConfig = (configFilePath, config) => fs_1.default.writeFileSync(configFilePath, JSON.stringify(config, null, '\t'));
+// ...
+class ATV {
+    addr;
+    port;
+    httpClient;
+    auth_secret;
+    constructor(addr, port) {
+        this.addr = addr;
+        this.port = port || 7000;
+        this.httpClient = (0, http_1.default)();
+        this.auth_secret = null;
+    }
+    // ...
+    auth(configFilePath, authenticator) {
+        async function auth(owner) {
+            await owner.httpClient.connect(owner.addr, owner.port);
+            let conf = loadConfig(configFilePath);
+            const authSecret = conf && typeof conf['auth_secret'] === 'string' ? conf['auth_secret'] : null;
+            if (!authSecret) {
+                // a pairing does not exist and must be performed.
+                // ...
+                // SRP parameters. 
+                const srp = new srp_1.default(2048);
+                const I = '366B4165DD64AD3A';
+                let P;
+                let s;
+                let B;
+                let a;
+                let A;
+                let M1;
+                await owner.httpClient.request('POST', '/pair-pin-start')
+                    .then(() => authenticator())
+                    .then(pin => {
+                    P = pin;
+                    return owner.httpClient.request('POST', '/pair-setup-pin', {
+                        'Content-Type': 'application/x-apple-binary-plist'
+                    }, (0, bplist_creator_1.default)({
+                        user: '366B4165DD64AD3A',
+                        method: 'pin'
+                    }));
+                })
+                    .then((res) => {
+                    const { pk, salt } = bplist_parser_1.default.parseBuffer(res.body)[0];
+                    s = salt.toString('hex');
+                    B = pk.toString('hex');
+                    // SRP: Generate random auth_secret, 'a'; if pairing is successful, it'll be utilized in 
+                    // subsequent session authentication(s).
+                    a = crypto_1.default.randomBytes(32).toString('hex');
+                    // SRP: Compute A and M1. 
+                    A = srp.A(a);
+                    M1 = srp.M1(I, P, s, a, B);
+                    return owner.httpClient.request('POST', '/pair-setup-pin', {
+                        'Content-Type': 'application/x-apple-binary-plist'
+                    }, (0, bplist_creator_1.default)({
+                        pk: Buffer.from(A, 'hex'),
+                        proof: Buffer.from(M1, 'hex')
+                    }));
+                })
+                    .then(() => {
+                    // confirm the auth secret (a).
+                    const { epk, authTag } = atvAuthenticator_1.default.confirm(a, srp.K(I, P, s, a, B));
+                    // complete pair-setup-pin by registering the auth secret with the target device.
+                    return owner.httpClient.request('POST', '/pair-setup-pin', {
+                        'Content-Type': 'application/x-apple-binary-plist'
+                    }, (0, bplist_creator_1.default)({
+                        epk: Buffer.from(epk, 'hex'),
+                        authTag: Buffer.from(authTag, 'hex')
+                    }));
+                })
+                    .then(() => {
+                    // save the auth secret for subsequent session authentication(s).
+                    if (!conf) {
+                        conf = {};
+                    }
+                    conf['auth_secret'] = a;
+                    saveConfig(configFilePath, conf);
+                });
+            }
+            // ...
+            // Authenticate session with the target device using existing pairing information.
+            const verifier = atvAuthenticator_1.default.verifier(conf?.['auth_secret'] ?? '');
+            return owner.httpClient.request('POST', '/pair-verify', {
+                'Content-Type': 'application/octet-stream'
+            }, verifier.verifierBody)
+                .then((res) => {
+                const atv_pub = res.body.slice(0, 32).toString('hex');
+                const atv_data = res.body.slice(32).toString('hex');
+                const shared = atvAuthenticator_1.default.shared(verifier.v_pri, atv_pub);
+                const signed = atvAuthenticator_1.default.signed(conf?.['auth_secret'] ?? '', verifier.v_pub, atv_pub);
+                const signature = Buffer.from(Buffer.from([0x00, 0x00, 0x00, 0x00]).toString('hex') +
+                    atvAuthenticator_1.default.signature(shared, atv_data, signed), 'hex');
+                return owner.httpClient.request('POST', '/pair-verify', {
+                    'Content-Type': 'application/octet-stream'
+                }, signature);
+            });
+        }
+        return auth(this);
+    }
+    authSecret() {
+        return this.auth_secret;
+    }
+    authSimple(authenticator) {
+        async function auth(owner) {
+            await owner.httpClient.connect(owner.addr, owner.port);
+            const conf = null;
+            if (!conf || !conf['auth_secret']) {
+                // a pairing does not exist and must be performed.
+                // ...
+                // SRP parameters. 
+                const srp = new srp_1.default(2048);
+                const I = '366B4165DD64AD3A';
+                let P;
+                let s;
+                let B;
+                let a;
+                let A;
+                let M1;
+                await owner.httpClient.request('POST', '/pair-pin-start')
+                    .then(() => authenticator())
+                    .then(pin => {
+                    P = pin;
+                    return owner.httpClient.request('POST', '/pair-setup-pin', {
+                        'Content-Type': 'application/x-apple-binary-plist'
+                    }, (0, bplist_creator_1.default)({
+                        user: '366B4165DD64AD3A',
+                        method: 'pin'
+                    }));
+                })
+                    .then((res) => {
+                    const { pk, salt } = bplist_parser_1.default.parseBuffer(res.body)[0];
+                    s = salt.toString('hex');
+                    B = pk.toString('hex');
+                    // SRP: Generate random auth_secret, 'a'; if pairing is successful, it'll be utilized in 
+                    // subsequent session authentication(s).
+                    a = crypto_1.default.randomBytes(32).toString('hex');
+                    // SRP: Compute A and M1. 
+                    A = srp.A(a);
+                    M1 = srp.M1(I, P, s, a, B);
+                    return owner.httpClient.request('POST', '/pair-setup-pin', {
+                        'Content-Type': 'application/x-apple-binary-plist'
+                    }, (0, bplist_creator_1.default)({
+                        pk: Buffer.from(A, 'hex'),
+                        proof: Buffer.from(M1, 'hex')
+                    }));
+                }).then(() => {
+                    // confirm the auth secret (a).
+                    const { epk, authTag } = atvAuthenticator_1.default.confirm(a, srp.K(I, P, s, a, B));
+                    // complete pair-setup-pin by registering the auth secret with the target device.
+                    return owner.httpClient.request('POST', '/pair-setup-pin', {
+                        'Content-Type': 'application/x-apple-binary-plist'
+                    }, (0, bplist_creator_1.default)({
+                        epk: Buffer.from(epk, 'hex'),
+                        authTag: Buffer.from(authTag, 'hex')
+                    }));
+                })
+                    .then(() => {
+                    // save the auth secret for subsequent session authentication(s).
+                    owner.auth_secret = a;
+                });
+            }
+        }
+        return auth(this);
+    }
+    verifySimple(secret) {
+        // ...
+        // Authenticate session with the target device using existing pairing information.
+        const verifier = atvAuthenticator_1.default.verifier(secret);
+        return this.httpClient.request('POST', '/pair-verify', {
+            'Content-Type': 'application/octet-stream',
+        }, verifier.verifierBody)
+            .then((res) => {
+            const atv_pub = res.body.slice(0, 32).toString('hex');
+            const atv_data = res.body.slice(32).toString('hex');
+            const shared = atvAuthenticator_1.default.shared(verifier.v_pri, atv_pub);
+            const signed = atvAuthenticator_1.default.signed(secret, verifier.v_pub, atv_pub);
+            const signature = Buffer.from(Buffer.from([0x00, 0x00, 0x00, 0x00]).toString('hex') +
+                atvAuthenticator_1.default.signature(shared, atv_data, signed), 'hex');
+            return this.httpClient.request('POST', '/pair-verify', {
+                'Content-Type': 'application/octet-stream',
+            }, signature);
+        });
+    }
+    play(videoUrl) {
+        return this.httpClient.request('POST', '/play', {
+            'Content-Type': 'application/x-apple-binary-plist'
+        }, (0, bplist_creator_1.default)({
+            'Content-Location': videoUrl,
+            'Start-Location': 0
+        }));
+    }
+    stop() {
+        return this.httpClient.request('POST', '/stop');
+    }
+    close() {
+        this.httpClient.close();
+    }
+}
+// ...
+exports.default = ATV;

package/dist/core/atvAuthenticator.d.ts

@@ -0,0 +1,30 @@
+declare function pair_setup_aes_key(K: string): string;
+declare function pair_setup_aes_iv(K: string): string;
+declare function pair_verify_aes_key(shared: string): string;
+declare function pair_verify_aes_iv(shared: string): string;
+declare function a_pub(a: string): string;
+declare function confirm(a: string, K: string): {
+    epk: string;
+    authTag: string;
+};
+declare function verifier(a: string): {
+    verifierBody: Buffer;
+    v_pri: string;
+    v_pub: string;
+};
+declare function shared(v_pri: string, atv_pub: string): string;
+declare function signed(a: string, v_pub: string, atv_pub: string): string;
+declare function signature(shared: string, atv_data: string, signed: string): string;
+declare const _default: {
+    pair_setup_aes_key: typeof pair_setup_aes_key;
+    pair_setup_aes_iv: typeof pair_setup_aes_iv;
+    pair_verify_aes_key: typeof pair_verify_aes_key;
+    pair_verify_aes_iv: typeof pair_verify_aes_iv;
+    a_pub: typeof a_pub;
+    confirm: typeof confirm;
+    verifier: typeof verifier;
+    shared: typeof shared;
+    signed: typeof signed;
+    signature: typeof signature;
+};
+export default _default;

package/dist/core/atvAuthenticator.js

@@ -0,0 +1,134 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const elliptic = require('elliptic');
+const crypto_1 = __importDefault(require("crypto"));
+const ed = __importStar(require("@noble/ed25519"));
+const util_1 = require("../utils/util");
+// ...
+// Note: All functions expect parameters to be hex strings.
+function pair_setup_aes_key(K) {
+    return crypto_1.default.createHash('sha512')
+        .update('Pair-Setup-AES-Key')
+        .update((0, util_1.hexString2ArrayBuffer)(K))
+        .digest('hex')
+        .substring(0, 32);
+}
+function pair_setup_aes_iv(K) {
+    let ab = crypto_1.default.createHash('sha512')
+        .update('Pair-Setup-AES-IV')
+        .update((0, util_1.hexString2ArrayBuffer)(K))
+        .digest();
+    ab = ab.slice(0, 16);
+    ab[ab.length - 1] += 0x01;
+    return (0, util_1.buf2hex)(ab);
+}
+function pair_verify_aes_key(shared) {
+    return (0, util_1.buf2hex)(crypto_1.default.createHash('sha512')
+        .update('Pair-Verify-AES-Key')
+        .update((0, util_1.hexString2ArrayBuffer)(shared))
+        .digest()
+        .slice(0, 16));
+}
+function pair_verify_aes_iv(shared) {
+    return (0, util_1.buf2hex)(crypto_1.default.createHash('sha512')
+        .update('Pair-Verify-AES-IV')
+        .update((0, util_1.hexString2ArrayBuffer)(shared))
+        .digest()
+        .slice(0, 16));
+}
+// ...
+// Public.
+function a_pub(a) {
+    return elliptic.utils.toHex(new elliptic.eddsa('ed25519').keyFromSecret(a).getPublic());
+}
+function confirm(a, K) {
+    const key = pair_setup_aes_key(K);
+    const iv = pair_setup_aes_iv(K);
+    const cipher = crypto_1.default.createCipheriv('aes-128-gcm', (0, util_1.hexString2ArrayBuffer)(key), (0, util_1.hexString2ArrayBuffer)(iv));
+    const encrypted = Buffer.concat([
+        cipher.update((0, util_1.hexString2ArrayBuffer)(a_pub(a))),
+        cipher.final(),
+    ]);
+    return {
+        epk: encrypted.toString('hex'),
+        authTag: (0, util_1.buf2hex)(cipher.getAuthTag()),
+    };
+}
+function verifier(a) {
+    const privateKey = Buffer.from(ed.utils.randomPrivateKey());
+    const publicKey = Buffer.from(ed.curve25519.scalarMultBase(privateKey));
+    const v_pri = (0, util_1.buf2hex)(privateKey);
+    const v_pub = (0, util_1.buf2hex)(publicKey);
+    const header = Buffer.from([0x01, 0x00, 0x00, 0x00]);
+    const a_pub_buf = Buffer.from(a_pub(a), 'hex');
+    return {
+        verifierBody: Buffer.concat([header, publicKey, a_pub_buf], header.byteLength + publicKey.byteLength + a_pub_buf.byteLength),
+        v_pri,
+        v_pub
+    };
+}
+function shared(v_pri, atv_pub) {
+    return (0, util_1.buf2hex)(Buffer.from(ed.curve25519.scalarMult((0, util_1.hexString2ArrayBuffer)(v_pri), (0, util_1.hexString2ArrayBuffer)(atv_pub))));
+}
+function signed(a, v_pub, atv_pub) {
+    const key = new elliptic.eddsa('ed25519').keyFromSecret(a);
+    return key.sign(v_pub + atv_pub).toHex();
+}
+function signature(shared, atv_data, signed) {
+    const cipher = crypto_1.default.createCipheriv('aes-128-ctr', (0, util_1.hexString2ArrayBuffer)(pair_verify_aes_key(shared)), (0, util_1.hexString2ArrayBuffer)(pair_verify_aes_iv(shared)));
+    // discard the result of encrypting atv_data.
+    cipher.update((0, util_1.hexString2ArrayBuffer)(atv_data));
+    const encrypted = Buffer.concat([
+        cipher.update(Buffer.from(signed, 'hex')),
+        cipher.final(),
+    ]);
+    return encrypted.toString('hex');
+}
+exports.default = {
+    pair_setup_aes_key,
+    pair_setup_aes_iv,
+    pair_verify_aes_key,
+    pair_verify_aes_iv,
+    a_pub,
+    confirm,
+    verifier,
+    shared,
+    signed,
+    signature,
+};

package/dist/core/audioOut.d.ts

@@ -0,0 +1,43 @@
+import { EventEmitter } from 'node:events';
+import type CircularBuffer from '../utils/circularBuffer';
+type DevicesEmitter = EventEmitter & {
+    on(event: 'airtunes_devices', listener: (hasAirTunes: boolean) => void): DevicesEmitter;
+    on(event: 'need_sync', listener: () => void): DevicesEmitter;
+    emit(event: 'underrun'): boolean;
+};
+/**
+ * Generates RTP timestamps and sequence, pulling PCM/ALAC packets from a circular buffer.
+ * Emits `packet` events for devices and sync requests (`need_sync`) at intervals.
+ */
+export default class AudioOut extends EventEmitter {
+    private lastSeq;
+    private lastWireSeq;
+    private hasAirTunes;
+    private rtpTimeRef;
+    private startTimeMs?;
+    private startTimeNtp?;
+    private latencyFrames;
+    private latencyApplied;
+    private seqOffset;
+    private tsOffset;
+    private syncOffsetFrames;
+    private deviceMagic;
+    private packetCount;
+    private octetCount;
+    private readonly frameDurationMs;
+    private muteUntilMs;
+    /**
+     * Begin pulling from the buffer and emitting packets at the configured cadence.
+     * @param devices Device manager for sync events.
+     * @param circularBuffer PCM/ALAC buffer.
+     * @param startTimeMs Optional unix ms to align playback.
+     * @param startTimeNtp Optional NTP uint64 (sec<<32|frac) to align playback.
+     */
+    init(devices: DevicesEmitter, circularBuffer: CircularBuffer, startTimeMs?: number, startTimeNtp?: bigint | number, deviceMagic?: number, underrunMuteMs?: number): void;
+    /**
+     * Apply latency (in audio frames) when aligning start time.
+     */
+    setLatencyFrames(latencyFrames: number): void;
+    private handleUnderrun;
+}
+export {};