test(audio): cover URL protocols and reconnects

.gitea/workflows/Build-Rollout.yml

@@ -6,11 +6,6 @@ on:
 permissions:
     contents: write
 
-env:
-    VERSION_MAJOR: '1'
-    VERSION_MINOR: '1'
-    VERSION_PATCH: ${{ gitea.run_number }}
-
 jobs:
     build:
         runs-on: ubuntu-latest
@@ -22,10 +17,10 @@ jobs:
                   fetch-depth: 0
                   fetch-tags: true
 
-            - name: Use NodeJS 24
+            - name: Use Node.js 24.17.0
               uses: actions/setup-node@v6
               with:
-                  node-version: '24'
+                  node-version: '24.17.0'
                   registry-url: 'https://registry.npmjs.org'
                   package-manager-cache: false
 
@@ -33,8 +28,9 @@ jobs:
               run: npm ci
 
             - name: Set Release Version
-              id: version
               run: npm run version:place
+              env:
+                  VERSION_PATCH: ${{ gitea.run_number }}
 
             - name: Export Release Version
               id: release_version

.gitea/workflows/Build-Validation.yml

@@ -15,10 +15,10 @@ jobs:
             - name: Checkout Repository
               uses: actions/checkout@v4
 
-            - name: use NodeJS 24
+            - name: Use Node.js 24.17.0
               uses: actions/setup-node@v4
               with:
-                  node-version: '24'
+                  node-version: '24.17.0'
 
             - name: Install Dependencies
               run: npm ci

README.md

@@ -1,8 +1,8 @@
 # Discord Audio Stream
 
-[![npm](https://img.shields.io/npm/dw/discord-audio-stream)](http://npmjs.org/package/discord-audio-stream)
+[![npm](https://img.shields.io/npm/dw/discord-audio-stream)](https://www.npmjs.com/package/discord-audio-stream)
 ![latest release](https://img.shields.io/gitea/v/release/FrauJulian/Discord-Audio-Stream?gitea_url=https%3A%2F%2Fgit.lechner-systems.at&color=blue)
-![Gitea Repo stars](https://img.shields.io/gitea/stars/FrauJulian/Discord-Audio-Stream?gitea_url=https%3A%2F%2Fgit.lechner-systems.at&style=social)
+![Github Repo stars](https://img.shields.io/github/stars/FrauJulian/Discord-Audio-Stream?github_url=https%3A%2F%2Fgithub.com&style=social)
 
 `discord-audio-stream` is a small TypeScript library for managed Discord voice playback through
 `@discordjs/voice` and ffmpeg.
@@ -18,7 +18,7 @@ Create an [issue](https://git.lechner-systems.at/FrauJulian/Discord-Audio-Stream
 
 ## Installation
 
-Node.js `24.x` is required.
+Node.js `>=22.12.0` and `<25` is required.
 
 ```bash
 npm install discord-audio-stream @discordjs/voice @discordjs/opus
@@ -114,6 +114,7 @@ type AudioManagerOptions = {
     };
     source?: { type: 'url'; url: string } | { type: 'file'; path: string };
     renewIntervalMs?: number | false;
+    reconnectAttempts?: number;
     connectTimeoutMs?: number;
     onError?: (error: Error) => void;
     volume?: {
@@ -123,21 +124,26 @@ type AudioManagerOptions = {
 };
 ```
 
+`connectTimeoutMs` and numeric `renewIntervalMs` values must be whole milliseconds from `1` through `2_147_483_647`.
+`reconnectAttempts` must be a non-negative safe integer. URL sources must use `http:` or `https:`.
+`volume.initialPercent` must be a finite number from `0` through `100` and requires `volume.enabled: true`.
+
 ### Defaults
 
-| Option             | Default    |
-| ------------------ | ---------- |
-| `ffmpeg.mode`      | `'native'` |
-| `connectTimeoutMs` | `20_000`   |
-| `renewIntervalMs`  | `false`    |
-| `volume.enabled`   | `false`    |
+| Option              | Default    |
+| ------------------- | ---------- |
+| `ffmpeg.mode`       | `'native'` |
+| `connectTimeoutMs`  | `20_000`   |
+| `renewIntervalMs`   | `false`    |
+| `reconnectAttempts` | `0`        |
+| `volume.enabled`    | `false`    |
 
 ### Methods
 
 | Method                   | Description                                                                        |
 | ------------------------ | ---------------------------------------------------------------------------------- |
-| `setConnection(options)` | Replaces the voice connection target.                                              |
-| `setSource(source)`      | Replaces the audio source.                                                         |
+| `setConnection(options)` | Sets the target for the next `connect()` or `start()` call.                        |
+| `setSource(source)`      | Sets the source for the next `play()` or `start()` call.                           |
 | `connect()`              | Joins the configured Discord voice channel.                                        |
 | `play(source?)`          | Starts playback on an existing connection.                                         |
 | `start()`                | Connects and starts playback.                                                      |
@@ -185,6 +191,9 @@ Connection renewal is disabled by default because `@discordjs/voice` handles rec
 `renewIntervalMs` only when an application has a measured need for periodic restarts. `stop()` and `dispose()` always
 clear the renewal timer.
 
+After an unrecoverable disconnect, playback stops by default. Set `reconnectAttempts` to retry joining the configured
+voice channel and restarting the current source.
+
 ## Errors
 
 The package exports these error classes:
@@ -200,6 +209,8 @@ operations, such as calling `pause()` while nothing is playing, throw `AudioMana
 Use `onError` to observe asynchronous audio player and voice connection errors. The manager cleans up failed playback
 and unrecoverable connections before invoking the callback.
 
+`onError` does not handle rejected `connect()`, `play()`, or `start()` calls. Await and catch those calls explicitly.
+
 ## Development
 
 ```bash

package-lock.json

@@ -7,7 +7,7 @@
         "": {
             "name": "discord-audio-stream",
             "version": "x.x.x",
-            "license": "LGPL-3.0-only",
+            "license": "AGPL-3.0-only",
             "devDependencies": {
                 "@discordjs/opus": "^0.10.0",
                 "@jest/globals": "^30.4.1",
@@ -31,7 +31,7 @@
                 "typescript": "npm:@typescript/typescript6@^6.0.2"
             },
             "engines": {
-                "node": "24.x"
+                "node": ">=22.12.0 <25"
             },
             "funding": {
                 "url": "https://ko-fi.com/FrauJulian"

package.json

@@ -2,7 +2,7 @@
     "$schema": "https://json.schemastore.org/package.json",
     "name": "discord-audio-stream",
     "version": "x.x.x",
-    "license": "LGPL-3.0-only",
+    "license": "AGPL-3.0-only",
     "description": "A small Discord voice audio streaming library with managed ffmpeg playback.",
     "exports": {
         ".": {
@@ -112,7 +112,7 @@
         "esbuild": "^0.28.2"
     },
     "engines": {
-        "node": "24.x"
+        "node": ">=22.12.0 <25"
     },
     "private": false,
     "publishConfig": {

set-version.js

@@ -3,6 +3,8 @@ const fs = require('fs');
 const lockFilePath = 'package-lock.json';
 const packageFilePath = 'package.json';
 const placeholderVersion = 'x.x.x';
+const versionMajor = 1;
+const versionMinor = 2;
 const command = process.argv[2];
 
 function readJson(path) {
@@ -24,7 +26,7 @@ function getLockFile() {
 function writeVersions(version) {
     const pkg = readJson(packageFilePath);
     pkg.version = version;
-    writeJson(packageFilePath, pkg, 2);
+    writeJson(packageFilePath, pkg, 4);
 
     const lock = getLockFile();
 
@@ -74,19 +76,14 @@ function fixPlaceholder() {
 }
 
 function getCiVersion() {
-    const major = process.env.VERSION_MAJOR;
-    const minor = process.env.VERSION_MINOR;
     const patch = process.env.VERSION_PATCH;
-    const segments = { major, minor, patch };
 
-    for (const [name, value] of Object.entries(segments)) {
-        if (!/^\d+$/.test(value ?? '')) {
-            console.error(`Missing or invalid ${name} version segment: "${value ?? ''}"`);
-            process.exit(1);
-        }
+    if (!/^\d+$/.test(patch ?? '')) {
+        console.error(`Missing or invalid patch version segment: "${patch ?? ''}"`);
+        process.exit(1);
     }
 
-    return `${major}.${minor}.${patch}`;
+    return `${versionMajor}.${versionMinor}.${patch}`;
 }
 
 if (command === 'check-placeholder') {

src/audio-manager.ts

@@ -48,6 +48,7 @@ export default class AudioManager implements Disposable {
     private connectAttempt: AbortController | undefined;
     private renewTimer: NodeJS.Timeout | undefined;
     private playbackState: PlaybackState = 'idle';
+    private reconnectGeneration = 0;
     private connectionOptions: VoiceConnectionOptions | undefined;
     private audioSource: AudioSource | undefined;
     private readonly options: Required<Pick<AudioManagerOptions, 'connectTimeoutMs'>> &
@@ -61,6 +62,13 @@ export default class AudioManager implements Disposable {
             assertValidTimerDelay(options.renewIntervalMs, 'renewIntervalMs');
         }
 
+        if (
+            options.reconnectAttempts !== undefined &&
+            (!Number.isSafeInteger(options.reconnectAttempts) || options.reconnectAttempts < 0)
+        ) {
+            throw new AudioManagerConfigError('reconnectAttempts must be a non-negative safe integer.');
+        }
+
         if (options.volume?.initialPercent !== undefined) {
             if (options.volume.enabled !== true) {
                 throw new AudioManagerConfigError('volume.initialPercent requires volume.enabled to be true.');
@@ -254,6 +262,7 @@ export default class AudioManager implements Disposable {
             return;
         }
 
+        this.reconnectGeneration += 1;
         this.cancelConnectAttempt();
         this.clearRenewTimer();
         this.stopCurrentPlayback();
@@ -285,6 +294,7 @@ export default class AudioManager implements Disposable {
             return;
         }
 
+        this.reconnectGeneration += 1;
         this.cancelConnectAttempt();
         this.clearRenewTimer();
         this.stopCurrentPlayback();
@@ -307,8 +317,13 @@ export default class AudioManager implements Disposable {
 
         if (this.audioSource.type === 'url') {
             try {
+                const url = new URL(this.audioSource.url);
+                if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+                    throw new Error('Unsupported audio source protocol.');
+                }
+
                 return {
-                    input: new URL(this.audioSource.url).toString(),
+                    input: url.toString(),
                     source: this.audioSource,
                 };
             } catch (error) {
@@ -361,6 +376,9 @@ export default class AudioManager implements Disposable {
     }
 
     private async handleDisconnectedConnection(connection: VoiceConnection): Promise<void> {
+        const shouldReconnect = this.resource !== undefined && (this.options.reconnectAttempts ?? 0) > 0;
+        const reconnectGeneration = this.reconnectGeneration;
+
         try {
             await Promise.race([
                 entersState(connection, VoiceConnectionStatus.Signalling, DISCONNECT_RECOVERY_TIMEOUT_MS),
@@ -371,6 +389,22 @@ export default class AudioManager implements Disposable {
                 return;
             }
 
+            if (shouldReconnect) {
+                this.clearRenewTimer();
+                for (let attempt = 0; attempt < (this.options.reconnectAttempts ?? 0); attempt += 1) {
+                    try {
+                        await this.start();
+                        return;
+                    } catch (reconnectError) {
+                        error = reconnectError;
+                    }
+
+                    if (this.reconnectGeneration !== reconnectGeneration || this.playbackState === 'disposed') {
+                        return;
+                    }
+                }
+            }
+
             this.clearRenewTimer();
             this.stopCurrentPlayback();
             this.audioPlayer.stop(true);

src/types.ts

@@ -112,7 +112,7 @@ export type VolumeOptions = {
     /**
      * Initial volume percentage applied when playback starts.
      *
-     * Requires `enabled: true`.
+     * Must be a finite number from `0` through `100` and requires `enabled: true`.
      */
     initialPercent?: number;
 };
@@ -144,13 +144,21 @@ export type AudioManagerOptions = {
      * Milliseconds after which the manager reconnects and restarts playback.
      *
      * Renewal is disabled unless an interval is provided.
+     * Numeric values must be integers from `1` through `2_147_483_647`.
      *
      * @defaultValue `false`
      */
     renewIntervalMs?: number | false;
 
+    /**
+     * Number of full reconnect and playback restart attempts after an unrecoverable disconnect.
+     * Disabled by default. Must be a non-negative safe integer.
+     */
+    reconnectAttempts?: number;
+
     /**
      * Maximum milliseconds to wait for the Discord voice connection to become ready.
+     * Must be an integer from `1` through `2_147_483_647`.
      *
      * @defaultValue `20_000`
      */

tests/audio-manager.test.ts

@@ -235,6 +235,28 @@ describe('AudioManager', () => {
         expect(manager.isConnected).toBe(false);
     });
 
+    it('reconnects and restarts playback when configured', async () => {
+        const manager = new AudioManager({
+            connection: connectionOptions,
+            source: liveStreamSource,
+            renewIntervalMs: false,
+            reconnectAttempts: 1,
+        });
+        await manager.start();
+        jest.mocked(entersState)
+            .mockRejectedValueOnce(new Error('disconnect'))
+            .mockRejectedValueOnce(new Error('disconnect'));
+        jest.mocked(joinVoiceChannel).mockReturnValueOnce(mockSecondVoiceConnection);
+        mockConnection.state.status = VoiceConnectionStatus.Disconnected;
+
+        await listenerFor(connectionListeners, VoiceConnectionStatus.Disconnected)();
+
+        expect(joinVoiceChannel).toHaveBeenCalledTimes(2);
+        expect(startFfmpeg).toHaveBeenCalledTimes(2);
+        expect(manager.state).toBe('playing');
+        expect(manager.isConnected).toBe(true);
+    });
+
     it('cleans up when connection startup fails', async () => {
         jest.useFakeTimers();
 
@@ -599,6 +621,18 @@ describe('AudioManager', () => {
         await expect(manager.play()).rejects.toThrow(AudioManagerConfigError);
     });
 
+    it.each(['file:///etc/passwd', 'ftp://example.com/audio.mp3'])('rejects non-HTTP URL source %s', async (url) => {
+        const manager = new AudioManager({
+            connection: connectionOptions,
+            source: { type: 'url', url },
+            renewIntervalMs: false,
+        });
+
+        await manager.connect();
+        await expect(manager.play()).rejects.toThrow(AudioManagerConfigError);
+        expect(startFfmpeg).not.toHaveBeenCalled();
+    });
+
     it('applies initial volume only when volume support is enabled', async () => {
         const manager = new AudioManager({
             connection: connectionOptions,