@ovencord/voice 0.19.0

package/src/audio/AudioResource.ts

@@ -0,0 +1,296 @@
+import type { Buffer } from 'node:buffer';
+import { pipeline, type Readable } from 'node:stream';
+import prism from 'prism-media';
+import { noop } from '../util/util';
+import { SILENCE_FRAME, type AudioPlayer } from './AudioPlayer';
+import { findPipeline, StreamType, TransformerType, type Edge } from './TransformerGraph';
+
+/**
+ * Options that are set when creating a new audio resource.
+ *
+ * @typeParam Metadata - the type for the metadata (if any) of the audio resource
+ */
+export interface CreateAudioResourceOptions<Metadata> {
+	/**
+	 * Whether or not inline volume should be enabled. If enabled, you will be able to change the volume
+	 * of the stream on-the-fly. However, this also increases the performance cost of playback. Defaults to `false`.
+	 */
+	inlineVolume?: boolean;
+
+	/**
+	 * The type of the input stream. Defaults to `StreamType.Arbitrary`.
+	 */
+	inputType?: StreamType;
+
+	/**
+	 * Optional metadata that can be attached to the resource (e.g. track title, random id).
+	 * This is useful for identification purposes when the resource is passed around in events.
+	 * See {@link AudioResource.metadata}
+	 */
+	metadata?: Metadata;
+
+	/**
+	 * The number of silence frames to append to the end of the resource's audio stream, to prevent interpolation glitches.
+	 * Defaults to 5.
+	 */
+	silencePaddingFrames?: number;
+}
+
+/**
+ * Represents an audio resource that can be played by an audio player.
+ *
+ * @typeParam Metadata - the type for the metadata (if any) of the audio resource
+ */
+export class AudioResource<Metadata = unknown> {
+	/**
+	 * An object-mode Readable stream that emits Opus packets. This is what is played by audio players.
+	 */
+	public readonly playStream: Readable;
+
+	/**
+	 * The pipeline used to convert the input stream into a playable format. For example, this may
+	 * contain an FFmpeg component for arbitrary inputs, and it may contain a VolumeTransformer component
+	 * for resources with inline volume transformation enabled.
+	 */
+	public readonly edges: readonly Edge[];
+
+	/**
+	 * Optional metadata that can be used to identify the resource.
+	 */
+	public metadata: Metadata;
+
+	/**
+	 * If the resource was created with inline volume transformation enabled, then this will be a
+	 * prism-media VolumeTransformer. You can use this to alter the volume of the stream.
+	 */
+	public readonly volume?: prism.VolumeTransformer;
+
+	/**
+	 * If using an Opus encoder to create this audio resource, then this will be a prism-media opus.Encoder.
+	 * You can use this to control settings such as bitrate, FEC, PLP.
+	 */
+	public readonly encoder?: prism.opus.Encoder;
+
+	/**
+	 * The audio player that the resource is subscribed to, if any.
+	 */
+	public audioPlayer?: AudioPlayer | undefined;
+
+	/**
+	 * The playback duration of this audio resource, given in milliseconds.
+	 */
+	public playbackDuration = 0;
+
+	/**
+	 * Whether or not the stream for this resource has started (data has become readable)
+	 */
+	public started = false;
+
+	/**
+	 * The number of silence frames to append to the end of the resource's audio stream, to prevent interpolation glitches.
+	 */
+	public readonly silencePaddingFrames: number;
+
+	/**
+	 * The number of remaining silence frames to play. If -1, the frames have not yet started playing.
+	 */
+	public silenceRemaining = -1;
+
+	public constructor(
+		edges: readonly Edge[],
+		streams: readonly Readable[],
+		metadata: Metadata,
+		silencePaddingFrames: number,
+	) {
+		this.edges = edges;
+		this.playStream = streams.length > 1 ? (pipeline(streams, noop) as any as Readable) : streams[0]!;
+		this.metadata = metadata;
+		this.silencePaddingFrames = silencePaddingFrames;
+
+		for (const stream of streams) {
+			if (stream instanceof prism.VolumeTransformer) {
+				this.volume = stream;
+			} else if (stream instanceof prism.opus.Encoder) {
+				this.encoder = stream;
+			}
+		}
+
+		this.playStream.once('readable', () => (this.started = true));
+	}
+
+	/**
+	 * Whether this resource is readable. If the underlying resource is no longer readable, this will still return true
+	 * while there are silence padding frames left to play.
+	 */
+	public get readable() {
+		if (this.silenceRemaining === 0) return false;
+		const real = this.playStream.readable;
+		if (!real) {
+			if (this.silenceRemaining === -1) this.silenceRemaining = this.silencePaddingFrames;
+			return this.silenceRemaining !== 0;
+		}
+
+		return real;
+	}
+
+	/**
+	 * Whether this resource has ended or not.
+	 */
+	public get ended() {
+		return this.playStream.readableEnded || this.playStream.destroyed || this.silenceRemaining === 0;
+	}
+
+	/**
+	 * Attempts to read an Opus packet from the audio resource. If a packet is available, the playbackDuration
+	 * is incremented.
+	 *
+	 * @remarks
+	 * It is advisable to check that the playStream is readable before calling this method. While no runtime
+	 * errors will be thrown, you should check that the resource is still available before attempting to
+	 * read from it.
+	 * @internal
+	 */
+	public read(): Buffer | null {
+		if (this.silenceRemaining === 0) {
+			return null;
+		} else if (this.silenceRemaining > 0) {
+			this.silenceRemaining--;
+			return SILENCE_FRAME;
+		}
+
+		const packet = this.playStream.read() as Buffer | null;
+		if (packet) {
+			this.playbackDuration += 20;
+		}
+
+		return packet;
+	}
+}
+
+/**
+ * Ensures that a path contains at least one volume transforming component.
+ *
+ * @param path - The path to validate constraints on
+ */
+export const VOLUME_CONSTRAINT = (path: Edge[]) => path.some((edge) => edge.type === TransformerType.InlineVolume);
+
+export const NO_CONSTRAINT = () => true;
+
+/**
+ * Tries to infer the type of a stream to aid with transcoder pipelining.
+ *
+ * @param stream - The stream to infer the type of
+ */
+export function inferStreamType(stream: Readable): {
+	hasVolume: boolean;
+	streamType: StreamType;
+} {
+	if (stream instanceof prism.opus.Encoder) {
+		return { streamType: StreamType.Opus, hasVolume: false };
+	} else if (stream instanceof prism.opus.Decoder) {
+		return { streamType: StreamType.Raw, hasVolume: false };
+	} else if (stream instanceof prism.VolumeTransformer) {
+		return { streamType: StreamType.Raw, hasVolume: true };
+	} else if (stream instanceof prism.opus.OggDemuxer) {
+		return { streamType: StreamType.Opus, hasVolume: false };
+	} else if (stream instanceof prism.opus.WebmDemuxer) {
+		return { streamType: StreamType.Opus, hasVolume: false };
+	}
+
+	return { streamType: StreamType.Arbitrary, hasVolume: false };
+}
+
+/**
+ * Creates an audio resource that can be played by audio players.
+ *
+ * @remarks
+ * If the input is given as a string, then the inputType option will be overridden and FFmpeg will be used.
+ *
+ * If the input is not in the correct format, then a pipeline of transcoders and transformers will be created
+ * to ensure that the resultant stream is in the correct format for playback. This could involve using FFmpeg,
+ * Opus transcoders, and Ogg/WebM demuxers.
+ * @param input - The resource to play
+ * @param options - Configurable options for creating the resource
+ * @typeParam Metadata - the type for the metadata (if any) of the audio resource
+ */
+export function createAudioResource<Metadata>(
+	input: Readable | string,
+	options: CreateAudioResourceOptions<Metadata> &
+		Pick<
+			Metadata extends null | undefined
+				? CreateAudioResourceOptions<Metadata>
+				: Required<CreateAudioResourceOptions<Metadata>>,
+			'metadata'
+		>,
+): AudioResource<Metadata extends null | undefined ? null : Metadata>;
+
+/**
+ * Creates an audio resource that can be played by audio players.
+ *
+ * @remarks
+ * If the input is given as a string, then the inputType option will be overridden and FFmpeg will be used.
+ *
+ * If the input is not in the correct format, then a pipeline of transcoders and transformers will be created
+ * to ensure that the resultant stream is in the correct format for playback. This could involve using FFmpeg,
+ * Opus transcoders, and Ogg/WebM demuxers.
+ * @param input - The resource to play
+ * @param options - Configurable options for creating the resource
+ * @typeParam Metadata - the type for the metadata (if any) of the audio resource
+ */
+export function createAudioResource<Metadata extends null | undefined>(
+	input: Readable | string,
+	options?: Omit<CreateAudioResourceOptions<Metadata>, 'metadata'>,
+): AudioResource<null>;
+
+/**
+ * Creates an audio resource that can be played by audio players.
+ *
+ * @remarks
+ * If the input is given as a string, then the inputType option will be overridden and FFmpeg will be used.
+ *
+ * If the input is not in the correct format, then a pipeline of transcoders and transformers will be created
+ * to ensure that the resultant stream is in the correct format for playback. This could involve using FFmpeg,
+ * Opus transcoders, and Ogg/WebM demuxers.
+ * @param input - The resource to play
+ * @param options - Configurable options for creating the resource
+ * @typeParam Metadata - the type for the metadata (if any) of the audio resource
+ */
+export function createAudioResource<Metadata>(
+	input: Readable | string,
+	options: CreateAudioResourceOptions<Metadata> = {},
+): AudioResource<Metadata> {
+	let inputType = options.inputType;
+	let needsInlineVolume = Boolean(options.inlineVolume);
+
+	// string inputs can only be used with FFmpeg
+	if (typeof input === 'string') {
+		inputType = StreamType.Arbitrary;
+	} else if (inputType === undefined) {
+		const analysis = inferStreamType(input);
+		inputType = analysis.streamType;
+		needsInlineVolume = needsInlineVolume && !analysis.hasVolume;
+	}
+
+	const transformerPipeline = findPipeline(inputType, needsInlineVolume ? VOLUME_CONSTRAINT : NO_CONSTRAINT);
+
+	if (transformerPipeline.length === 0) {
+		if (typeof input === 'string') throw new Error(`Invalid pipeline constructed for string resource '${input}'`);
+		// No adjustments required
+		return new AudioResource<Metadata>(
+			[],
+			[input],
+			(options.metadata ?? null) as Metadata,
+			options.silencePaddingFrames ?? 5,
+		);
+	}
+
+	const streams = transformerPipeline.map((edge) => edge.transformer(input));
+	if (typeof input !== 'string') streams.unshift(input);
+
+	return new AudioResource<Metadata>(
+		transformerPipeline,
+		streams,
+		(options.metadata ?? null) as Metadata,
+		options.silencePaddingFrames ?? 5,
+	);
+}

package/src/audio/PlayerSubscription.ts

@@ -0,0 +1,33 @@
+/* eslint-disable @typescript-eslint/dot-notation */
+import type { VoiceConnection } from '../VoiceConnection';
+import type { AudioPlayer } from './AudioPlayer';
+
+/**
+ * Represents a subscription of a voice connection to an audio player, allowing
+ * the audio player to play audio on the voice connection.
+ */
+export class PlayerSubscription {
+	/**
+	 * The voice connection of this subscription.
+	 */
+	public readonly connection: VoiceConnection;
+
+	/**
+	 * The audio player of this subscription.
+	 */
+	public readonly player: AudioPlayer;
+
+	public constructor(connection: VoiceConnection, player: AudioPlayer) {
+		this.connection = connection;
+		this.player = player;
+	}
+
+	/**
+	 * Unsubscribes the connection from the audio player, meaning that the
+	 * audio player cannot stream audio to it until a new subscription is made.
+	 */
+	public unsubscribe() {
+		this.connection['onSubscriptionRemoved'](this);
+		this.player['unsubscribe'](this);
+	}
+}

package/src/audio/TransformerGraph.ts

@@ -0,0 +1,281 @@
+import type { Readable } from 'node:stream';
+import prism from 'prism-media';
+
+/**
+ * This module creates a Transformer Graph to figure out what the most efficient way
+ * of transforming the input stream into something playable would be.
+ */
+
+const FFMPEG_PCM_ARGUMENTS = ['-analyzeduration', '0', '-loglevel', '0', '-f', 's16le', '-ar', '48000', '-ac', '2'];
+const FFMPEG_OPUS_ARGUMENTS = [
+	'-analyzeduration',
+	'0',
+	'-loglevel',
+	'0',
+	'-acodec',
+	'libopus',
+	'-f',
+	'opus',
+	'-ar',
+	'48000',
+	'-ac',
+	'2',
+];
+
+/**
+ * The different types of stream that can exist within the pipeline.
+ */
+export enum StreamType {
+	/**
+	 * The type of the stream at this point is unknown.
+	 */
+	Arbitrary = 'arbitrary',
+	/**
+	 * The stream at this point is Opus audio encoded in an Ogg wrapper.
+	 */
+	OggOpus = 'ogg/opus',
+	/**
+	 * The stream at this point is Opus audio, and the stream is in object-mode. This is ready to play.
+	 */
+	Opus = 'opus',
+	/**
+	 * The stream at this point is s16le PCM.
+	 */
+	Raw = 'raw',
+	/**
+	 * The stream at this point is Opus audio encoded in a WebM wrapper.
+	 */
+	WebmOpus = 'webm/opus',
+}
+
+/**
+ * The different types of transformers that can exist within the pipeline.
+ */
+export enum TransformerType {
+	FFmpegOgg = 'ffmpeg ogg',
+	FFmpegPCM = 'ffmpeg pcm',
+	InlineVolume = 'volume transformer',
+	OggOpusDemuxer = 'ogg/opus demuxer',
+	OpusDecoder = 'opus decoder',
+	OpusEncoder = 'opus encoder',
+	WebmOpusDemuxer = 'webm/opus demuxer',
+}
+
+/**
+ * Represents a pathway from one stream type to another using a transformer.
+ */
+export interface Edge {
+	cost: number;
+	from: Node;
+	to: Node;
+	transformer(input: Readable | string): Readable;
+	type: TransformerType;
+}
+
+/**
+ * Represents a type of stream within the graph, e.g. an Opus stream, or a stream of raw audio.
+ */
+export class Node {
+	/**
+	 * The outbound edges from this node.
+	 */
+	public readonly edges: Edge[] = [];
+
+	/**
+	 * The type of stream for this node.
+	 */
+	public readonly type: StreamType;
+
+	public constructor(type: StreamType) {
+		this.type = type;
+	}
+
+	/**
+	 * Creates an outbound edge from this node.
+	 *
+	 * @param edge - The edge to create
+	 */
+	public addEdge(edge: Omit<Edge, 'from'>) {
+		this.edges.push({ ...edge, from: this });
+	}
+}
+
+// Create a node for each stream type
+let NODES: Map<StreamType, Node> | null = null;
+
+/**
+ * Gets a node from its stream type.
+ *
+ * @param type - The stream type of the target node
+ */
+export function getNode(type: StreamType) {
+	const node = (NODES ??= initializeNodes()).get(type);
+	if (!node) throw new Error(`Node type '${type}' does not exist!`);
+	return node;
+}
+
+// Try to enable FFmpeg Ogg optimizations
+function canEnableFFmpegOptimizations(): boolean {
+	try {
+		return prism.FFmpeg.getInfo().output.includes('--enable-libopus');
+	} catch {}
+
+	return false;
+}
+
+function initializeNodes(): Map<StreamType, Node> {
+	const nodes = new Map<StreamType, Node>();
+	for (const streamType of Object.values(StreamType)) {
+		nodes.set(streamType, new Node(streamType));
+	}
+
+	nodes.get(StreamType.Raw)!.addEdge({
+		type: TransformerType.OpusEncoder,
+		to: nodes.get(StreamType.Opus)!,
+		cost: 1.5,
+		transformer: () => new prism.opus.Encoder({ rate: 48_000, channels: 2, frameSize: 960 }),
+	});
+
+	nodes.get(StreamType.Opus)!.addEdge({
+		type: TransformerType.OpusDecoder,
+		to: nodes.get(StreamType.Raw)!,
+		cost: 1.5,
+		transformer: () => new prism.opus.Decoder({ rate: 48_000, channels: 2, frameSize: 960 }),
+	});
+
+	nodes.get(StreamType.OggOpus)!.addEdge({
+		type: TransformerType.OggOpusDemuxer,
+		to: nodes.get(StreamType.Opus)!,
+		cost: 1,
+		transformer: () => new prism.opus.OggDemuxer(),
+	});
+
+	nodes.get(StreamType.WebmOpus)!.addEdge({
+		type: TransformerType.WebmOpusDemuxer,
+		to: nodes.get(StreamType.Opus)!,
+		cost: 1,
+		transformer: () => new prism.opus.WebmDemuxer(),
+	});
+
+	const FFMPEG_PCM_EDGE: Omit<Edge, 'from'> = {
+		type: TransformerType.FFmpegPCM,
+		to: nodes.get(StreamType.Raw)!,
+		cost: 2,
+		transformer: (input) =>
+			new prism.FFmpeg({
+				args: ['-i', typeof input === 'string' ? input : '-', ...FFMPEG_PCM_ARGUMENTS],
+			}),
+	};
+
+	nodes.get(StreamType.Arbitrary)!.addEdge(FFMPEG_PCM_EDGE);
+	nodes.get(StreamType.OggOpus)!.addEdge(FFMPEG_PCM_EDGE);
+	nodes.get(StreamType.WebmOpus)!.addEdge(FFMPEG_PCM_EDGE);
+
+	nodes.get(StreamType.Raw)!.addEdge({
+		type: TransformerType.InlineVolume,
+		to: nodes.get(StreamType.Raw)!,
+		cost: 0.5,
+		transformer: () => new prism.VolumeTransformer({ type: 's16le' }),
+	});
+
+	if (canEnableFFmpegOptimizations()) {
+		const FFMPEG_OGG_EDGE: Omit<Edge, 'from'> = {
+			type: TransformerType.FFmpegOgg,
+			to: nodes.get(StreamType.OggOpus)!,
+			cost: 2,
+			transformer: (input) =>
+				new prism.FFmpeg({
+					args: ['-i', typeof input === 'string' ? input : '-', ...FFMPEG_OPUS_ARGUMENTS],
+				}),
+		};
+		nodes.get(StreamType.Arbitrary)!.addEdge(FFMPEG_OGG_EDGE);
+		// Include Ogg and WebM as well in case they have different sampling rates or are mono instead of stereo
+		// at the moment, this will not do anything. However, if/when detection for correct Opus headers is
+		// implemented, this will help inform the voice engine that it is able to transcode the audio.
+		nodes.get(StreamType.OggOpus)!.addEdge(FFMPEG_OGG_EDGE);
+		nodes.get(StreamType.WebmOpus)!.addEdge(FFMPEG_OGG_EDGE);
+	}
+
+	return nodes;
+}
+
+/**
+ * Represents a step in the path from node A to node B.
+ */
+interface Step {
+	/**
+	 * The cost of the steps after this step.
+	 */
+	cost: number;
+
+	/**
+	 * The edge associated with this step.
+	 */
+	edge?: Edge;
+
+	/**
+	 * The next step.
+	 */
+	next?: Step;
+}
+
+/**
+ * Finds the shortest cost path from node A to node B.
+ *
+ * @param from - The start node
+ * @param constraints - Extra validation for a potential solution. Takes a path, returns true if the path is valid
+ * @param goal - The target node
+ * @param path - The running path
+ * @param depth - The number of remaining recursions
+ */
+function findPath(
+	from: Node,
+	constraints: (path: Edge[]) => boolean,
+	goal = getNode(StreamType.Opus),
+	path: Edge[] = [],
+	depth = 5,
+): Step {
+	if (from === goal && constraints(path)) {
+		return { cost: 0 };
+	} else if (depth === 0) {
+		return { cost: Number.POSITIVE_INFINITY };
+	}
+
+	let currentBest: Step | undefined;
+	for (const edge of from.edges) {
+		if (currentBest && edge.cost > currentBest.cost) continue;
+		const next = findPath(edge.to, constraints, goal, [...path, edge], depth - 1);
+		const cost = edge.cost + next.cost;
+		if (!currentBest || cost < currentBest.cost) {
+			currentBest = { cost, edge, next };
+		}
+	}
+
+	return currentBest ?? { cost: Number.POSITIVE_INFINITY };
+}
+
+/**
+ * Takes the solution from findPath and assembles it into a list of edges.
+ *
+ * @param step - The first step of the path
+ */
+function constructPipeline(step: Step) {
+	const edges = [];
+	let current: Step | undefined = step;
+	while (current?.edge) {
+		edges.push(current.edge);
+		current = current.next;
+	}
+
+	return edges;
+}
+
+/**
+ * Finds the lowest-cost pipeline to convert the input stream type into an Opus stream.
+ *
+ * @param from - The stream type to start from
+ * @param constraint - Extra constraints that may be imposed on potential solution
+ */
+export function findPipeline(from: StreamType, constraint: (path: Edge[]) => boolean) {
+	return constructPipeline(findPath(getNode(from), constraint));
+}

package/src/audio/index.ts

@@ -0,0 +1,20 @@
+export {
+	AudioPlayer,
+	AudioPlayerStatus,
+	type AudioPlayerState,
+	NoSubscriberBehavior,
+	createAudioPlayer,
+	type AudioPlayerBufferingState,
+	type AudioPlayerIdleState,
+	type AudioPlayerPausedState,
+	type AudioPlayerPlayingState,
+	type CreateAudioPlayerOptions,
+} from './AudioPlayer';
+
+export { AudioPlayerError } from './AudioPlayerError';
+
+export { AudioResource, type CreateAudioResourceOptions, createAudioResource } from './AudioResource';
+
+export { PlayerSubscription } from './PlayerSubscription';
+
+export { StreamType, type Edge, TransformerType, Node } from './TransformerGraph';

package/src/index.ts

@@ -0,0 +1,47 @@
+export * from './joinVoiceChannel';
+export * from './audio/index';
+export * from './util/index';
+export * from './receive/index';
+
+export {
+	Networking,
+	type ConnectionData,
+	type ConnectionOptions,
+	type NetworkingState,
+	type NetworkingResumingState,
+	type NetworkingSelectingProtocolState,
+	type NetworkingUdpHandshakingState,
+	type NetworkingClosedState,
+	type NetworkingIdentifyingState,
+	type NetworkingOpeningWsState,
+	type NetworkingReadyState,
+	NetworkingStatusCode,
+	VoiceUDPSocket,
+	VoiceWebSocket,
+	type SocketConfig,
+	DAVESession,
+} from './networking/index.js';
+
+export {
+	VoiceConnection,
+	type VoiceConnectionState,
+	VoiceConnectionStatus,
+	type VoiceConnectionConnectingState,
+	type VoiceConnectionDestroyedState,
+	type VoiceConnectionDisconnectedState,
+	type VoiceConnectionDisconnectedBaseState,
+	type VoiceConnectionDisconnectedOtherState,
+	type VoiceConnectionDisconnectedWebSocketState,
+	VoiceConnectionDisconnectReason,
+	type VoiceConnectionReadyState,
+	type VoiceConnectionSignallingState,
+} from './VoiceConnection';
+
+export { type JoinConfig, getVoiceConnection, getVoiceConnections, getGroups } from './DataStore';
+
+/**
+ * The {@link https://github.com/ovencord/ovencord/blob/main/packages/voice#readme | @ovencord/voice} version
+ * that you are currently using.
+ */
+// This needs to explicitly be `string` so it is not typed as a "const string" that gets injected by esbuild
+export const version = '[VI]{{inject}}[/VI]' as string;