@remedia/node 0.0.0-stage → 0.1.0-dev.1

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,126 @@
+# Third-party notices
+
+Remedia is licensed under MIT; see `LICENSE`. Third-party dependencies retain their own terms.
+This page highlights the major components. The accompanying `THIRD_PARTY_LICENSES.txt` reproduces
+additional upstream copyright notices, conditions, and disclaimers required for redistribution,
+including native Rust dependencies, Unicode data, and the Rust standard library. Keep both notice
+files with redistributed packages and binaries.
+
+## FFmpeg 7 — independently installed runtime libraries
+
+Remedia dynamically links FFmpeg 7. Consumers install the shared libraries independently; they are
+not bundled in Remedia's npm packages or standalone server binaries. FFmpeg's licensing depends on
+the selected build, enabled components, and external libraries. GPL-enabled builds are not rejected.
+Users must comply with applicable licensing requirements for their chosen build and deployment.
+See [official licensing information](https://ffmpeg.org/legal.html) and
+[FFmpeg source code](https://git.ffmpeg.org/ffmpeg.git).
+
+The Rust `ffmpeg-next` and `ffmpeg-sys-next` bindings have separate WTFPL terms, reproduced in the
+license appendix; those terms do not apply to FFmpeg itself.
+
+## libopus — statically included
+
+`opus2` 0.4.0 uses `libopus_sys` 0.3.3 with the bundled libopus backend. Its Opus source is compiled
+and statically linked into the native addon and standalone server. A system libopus is not needed.
+The bundled source's `opus/COPYING` is reproduced verbatim below. See
+[Opus source](https://gitlab.xiph.org/xiph/opus) and [official licensing](https://opus-codec.org/license/).
+
+```text
+Copyright 2001-2023 Xiph.Org, Skype Limited, Octasic,
+                    Jean-Marc Valin, Timothy B. Terriberry,
+                    CSIRO, Gregory Maxwell, Mark Borgerding,
+                    Erik de Castro Lopo, Mozilla, Amazon
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+- Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+- Neither the name of Internet Society, IETF or IETF Trust, nor the
+names of specific contributors, may be used to endorse or promote
+products derived from this software without specific prior written
+permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Opus is subject to the royalty-free patent licenses which are
+specified at:
+
+Xiph.Org Foundation:
+https://datatracker.ietf.org/ipr/1524/
+
+Microsoft Corporation:
+https://datatracker.ietf.org/ipr/1914/
+
+Broadcom Corporation:
+https://datatracker.ietf.org/ipr/1526/
+```
+
+The bundled source also supplies this `opus/LICENSE_PLEASE_READ.txt`:
+
+```text
+Contributions to the collaboration shall not be considered confidential.
+
+Each contributor represents and warrants that it has the right and
+authority to license copyright in its contributions to the collaboration.
+
+Each contributor agrees to license the copyright in the contributions
+under the Modified (2-clause or 3-clause) BSD License or the Clear BSD License.
+
+Please see the IPR statements submitted to the IETF for the complete
+patent licensing details:
+
+Xiph.Org Foundation:
+https://datatracker.ietf.org/ipr/1524/
+
+Microsoft Corporation:
+https://datatracker.ietf.org/ipr/1914/
+
+Skype Limited:
+https://datatracker.ietf.org/ipr/1602/
+
+Broadcom Corporation:
+https://datatracker.ietf.org/ipr/1526/
+```
+
+## Discord voice and cryptography
+
+[DAVE (`davey` 0.2.0)](https://crates.io/crates/davey/0.2.0) and
+[OpenMLS 0.8.3](https://crates.io/crates/openmls/0.8.3) provide native voice encryption components
+under their upstream MIT terms. Native TLS/crypto also incorporates
+[ring 0.17.14](https://crates.io/crates/ring/0.17.14), whose Apache-2.0 and ISC notices include
+BoringSSL-derived code. Their actual license and copyright notices are in `THIRD_PARTY_LICENSES.txt`.
+
+HPKE components are MPL-2.0 covered and used unmodified. Corresponding source is available from
+these exact published archives: [hpke-rs 0.6.1](https://crates.io/api/v1/crates/hpke-rs/0.6.1/download),
+[hpke-rs-crypto 0.6.1](https://crates.io/api/v1/crates/hpke-rs-crypto/0.6.1/download),
+[hpke-rs-libcrux 0.6.1](https://crates.io/api/v1/crates/hpke-rs-libcrux/0.6.1/download), and
+[hpke-rs-rust-crypto 0.6.1](https://crates.io/api/v1/crates/hpke-rs-rust-crypto/0.6.1/download).
+The MPL-2.0 text is in the license appendix. Redistributors must preserve source availability and
+applicable notices, including for any modifications they make.
+
+## JavaScript runtime dependency
+
+The client uses [ws 8.22.1](https://registry.npmjs.org/ws/-/ws-8.22.1.tgz), installed separately by
+npm under MIT terms. Its full copyright and license text is in `THIRD_PARTY_LICENSES.txt`.
+The packages compile with `tsc`; development tools and documentation-site dependencies are not
+bundled into the npm libraries or standalone server.
+
+Review these files when dependencies, native build options, or distributed artifacts change.
+Their presence does not guarantee legal compliance.

package/dist/discord.d.ts

@@ -0,0 +1,149 @@
+import { RemediaEventEmitter } from './events.js';
+import { PlaybackHooks, type PlayOptions, type SessionLifecycleEvents } from './lifecycle.js';
+import { FilterControls } from './filters.js';
+import type { MediaSource } from './input.js';
+import type { AudioStreamInfo, PlaybackPosition, PlaybackState, VoiceConnectionState } from './types.js';
+/**
+ * Identity, initial playback configuration, and Gateway voice flags for one guild session. The channel is a mutable destination, while userId identifies the bot.
+ */
+export interface DiscordSessionOptions {
+    /** Discord server snowflake as a decimal string. */
+    guildId: string;
+    /** Voice channel snowflake as a decimal string. */
+    channelId: string;
+    /** Bot user snowflake as a decimal string. */
+    userId: string;
+    /** Discord Gateway self-deaf state; defaults to true. */
+    selfDeaf?: boolean;
+    /** Discord Gateway self-mute state; defaults to false. */
+    selfMute?: boolean;
+    /** Session master linear gain, finite from 0 through 2; defaults to 1. */
+    volume?: number;
+    /** Trusted raw FFmpeg audio filtergraph; defaults to null. Native syntax validation occurs during backend configuration before playback. */
+    filterGraph?: string | null;
+}
+/** Cancellation and timeout controls for obtaining credentials and establishing a voice transport. */
+export interface DiscordConnectOptions {
+    /** Optional signal that cancels Gateway negotiation and pending transport setup. */
+    signal?: AbortSignal;
+    /** Maximum time to receive Gateway credentials and establish voice transport/DAVE. */
+    timeoutMs?: number;
+}
+/**
+ * One Discord voice session. The caller supplies a Gateway send adapter to `Remedia.create()` and
+ * forwards raw dispatch packets to `Remedia.receive()`; this session collects the matching voice
+ * credentials and opens the native transport after both dispatches arrive.
+ * @typeParam Metadata - Application-owned metadata attached to playback generations.
+ */
+export declare class DiscordSession<Metadata = unknown> extends RemediaEventEmitter<SessionLifecycleEvents<Metadata>> {
+    #private;
+    /** Opaque Remedia session identity used to correlate events; distinct from the Discord bot user ID. */
+    readonly sessionId: `${string}-${string}-${string}-${string}-${string}`;
+    /** Discord guild snowflake as a decimal string; unique within the owning client. */
+    readonly guildId: string;
+    /** Discord bot user snowflake as a decimal string; separate from Remedia session identity. */
+    readonly userId: string;
+    /** Persistent raw FFmpeg filtergraph controls for this session. */
+    readonly filters: FilterControls;
+    /** Ordered, awaited local pre-play hooks; listeners are separate from hooks. */
+    readonly hooks: PlaybackHooks<Metadata>;
+    /** Current requested voice destination; independent of playback identity. */
+    get channelId(): string;
+    /** Discord Gateway self-deaf state; defaults to true and persists across moves and recovery. */
+    get selfDeaf(): boolean;
+    /** Discord Gateway self-mute state; defaults to false and persists across moves and recovery. */
+    get selfMute(): boolean;
+    /**
+     * Replace only the voice transport. A newer move supersedes a pending move.
+     * @param channelId - Destination Discord voice channel snowflake as a positive decimal string.
+     * @returns Resolves when the requested destination connects; rejects on supersession, cancellation, or connection failure.
+     */
+    move(channelId: string): Promise<void>;
+    /**
+     * Update Discord self-deaf state without rebuilding playback. Unchanged values send nothing.
+     * @param enabled - The requested Discord self-state flag.
+     * @returns Resolves after storing the flag or sending its Gateway update; rejects if the update fails.
+     */
+    setSelfDeaf(enabled: boolean): Promise<void>;
+    /**
+     * Update Discord self-mute state without changing audio gain or playback pause. Unchanged values send nothing.
+     * @param enabled - The requested Discord self-state flag.
+     * @returns Resolves after storing the flag or sending its Gateway update; rejects if the update fails.
+     */
+    setSelfMute(enabled: boolean): Promise<void>;
+    /** Current voice transport state. A connected voice WebSocket may temporarily be reconnecting. */
+    get connectionState(): VoiceConnectionState;
+    /** Most recent Gateway or native transport failure, if any. */
+    get connectionError(): string | null;
+    /** Current playback lifecycle state. */
+    get state(): PlaybackState;
+    /** Latest source and output timeline measurements in milliseconds. */
+    get position(): PlaybackPosition;
+    /** Source duration in milliseconds, or null when unknown. */
+    get durationMs(): number | null;
+    /** Most recent playback or voice failure message, or null when no error is available. */
+    get error(): string | null;
+    /** Current normalized linear master gain, from 0.0 (mute) through 2.0. */
+    get volume(): number;
+    /** Current native source generation, useful to adapters that preserve event correlation. */
+    get generation(): number;
+    /**
+     * Set master gain independently of this session's configured filtergraph.
+     * @param gain - Finite linear master gain from 0 through 2; 1 leaves amplitude unchanged.
+     * @returns Resolves after the gain is stored or applied; rejects for non-finite gain or values outside 0 through 2.
+     * @throws {RangeError} If gain is non-finite or outside the inclusive range 0 through 2.
+     */
+    setVolume(gain: number): Promise<void>;
+    /**
+     * Request a Gateway voice join and wait until both voice dispatches have arrived and the native
+     * voice transport has completed its DAVE setup. Repeated calls while connecting share a promise.
+     * @param options - Optional cancellation signal and positive timeout in milliseconds; defaults to 45000.
+     * @returns Resolves when connected; rejects on timeout, cancellation, session loss, or transport failure.
+     */
+    connect(options?: DiscordConnectOptions): Promise<void>;
+    /**
+     * Begin playback on this connected voice session. The decoder and Opus encoder remain in core;
+     * this object only associates their output with the native Discord transport.
+     * @param source - Encoded media input; Buffer and caller-owned binary Readable inputs require embedded mode.
+     * @param options - Optional metadata for this generation and a cancellation signal.
+     * @returns Selected stream metadata once startup succeeds; rejects if hooks, input opening, or playback startup fail.
+     */
+    play(source: MediaSource, options?: PlayOptions<Metadata>): Promise<AudioStreamInfo>;
+    /**
+     * Pause the current playback without replacing its decoder or source generation.
+     * @returns Resolves when the backend accepts the pause request.
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume paused playback on its existing source generation.
+     * @returns Resolves when the backend accepts the resume request.
+     */
+    resume(): Promise<void>;
+    /**
+     * Seek on the original media timeline; non-seekable and one-shot sources may reject.
+     * @param positionMs - Non-negative finite position on the original media timeline, in milliseconds.
+     * @returns Resolves after the backend accepts the seek; rejects for invalid positions or unsupported inputs.
+     */
+    seek(positionMs: number): Promise<void>;
+    /**
+     * Stop the active playback generation and release its input without leaving the voice channel.
+     * @returns Resolves after the backend stops the active source.
+     */
+    stop(): Promise<void>;
+    /**
+     * Wait for the current playback generation to reach a terminal state.
+     * @returns The terminal playback state for the generation captured by this wait.
+     */
+    wait(): Promise<PlaybackState>;
+    /**
+     * Leave the Discord channel through Gateway OP 4 and close the native transport. This does not
+     * dispose the wrapper, so `connect()` can be called again with fresh Gateway dispatches.
+     * @returns Resolves after cleanup; concurrent disconnects share cleanup work.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Disconnect and unregister this session.
+     * @returns Resolves after disposal; rejects if resource cleanup fails.
+     */
+    dispose(): Promise<void>;
+}