@flighthq/media 0.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@flighthq/media",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/audio": "0.1.0",
+    "@flighthq/video": "0.1.0",
+    "@flighthq/signals": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Audio and video playback channels",
+  "sideEffects": false
+}

package/src/audioChannel.test.ts

@@ -0,0 +1,207 @@
+import { createAudioResource } from '@flighthq/audio';
+
+import {
+  connectAudioChannelToNode,
+  fadeAudioChannelGain,
+  getAudioChannelCurrentTime,
+  getAudioChannelDuration,
+  getAudioChannelInputNode,
+  getAudioChannelOutputNode,
+  isAudioChannelPlaying,
+  pauseAudioChannel,
+  playAudioResource,
+  resumeAudioChannel,
+  setAudioChannelCurrentTime,
+  setAudioChannelGain,
+  setAudioChannelPlaybackRate,
+  stopAudioChannel,
+} from './audioChannel';
+
+class MockAudioBufferSourceNode {
+  buffer: AudioBuffer | null = null;
+  onended: (() => void) | null = null;
+  playbackRate = { value: 1 };
+
+  connect(): void {}
+  start(): void {}
+  stop(): void {}
+}
+
+class MockAudioContext {
+  currentTime = 0;
+  destination = {};
+  state = 'running';
+
+  createBufferSource(): AudioBufferSourceNode {
+    return new MockAudioBufferSourceNode() as unknown as AudioBufferSourceNode;
+  }
+
+  createGain(): GainNode {
+    return {
+      connect() {},
+      disconnect() {},
+      gain: { value: 1 },
+    } as unknown as GainNode;
+  }
+
+  resume(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+const ctx = new MockAudioContext() as unknown as AudioContext;
+
+function createMockAudioBuffer(): AudioBuffer {
+  return { duration: 1 } as AudioBuffer;
+}
+
+describe('connectAudioChannelToNode', () => {
+  it('reroutes the active gain node to the destination without error', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    const destination = {} as AudioNode;
+    expect(() => connectAudioChannelToNode(channel!, destination)).not.toThrow();
+  });
+});
+
+describe('fadeAudioChannelGain', () => {
+  it('updates the channel gain immediately when no gain node is active', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    stopAudioChannel(channel!);
+    fadeAudioChannelGain(channel!, 0.5, 500);
+    expect(channel!.gain).toBe(0.5);
+  });
+});
+
+describe('getAudioChannelCurrentTime', () => {
+  it('returns the stored current time for an inactive channel', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()), { currentTime: 250 });
+    expect(channel).not.toBeNull();
+    pauseAudioChannel(channel!);
+    expect(getAudioChannelCurrentTime(channel!)).toBe(250);
+  });
+});
+
+describe('getAudioChannelDuration', () => {
+  it('returns the channel length', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    expect(getAudioChannelDuration(channel!)).toBe(1000);
+  });
+});
+
+describe('getAudioChannelInputNode', () => {
+  it('returns the source node while playing', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    expect(getAudioChannelInputNode(channel!)).not.toBeNull();
+  });
+
+  it('returns null after stop', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    stopAudioChannel(channel!);
+    expect(getAudioChannelInputNode(channel!)).toBeNull();
+  });
+});
+
+describe('getAudioChannelOutputNode', () => {
+  it('returns the gain node while playing', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    expect(getAudioChannelOutputNode(channel!)).not.toBeNull();
+  });
+
+  it('returns null after stop', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    stopAudioChannel(channel!);
+    expect(getAudioChannelOutputNode(channel!)).toBeNull();
+  });
+});
+
+describe('isAudioChannelPlaying', () => {
+  it('returns true while playing', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    expect(isAudioChannelPlaying(channel!)).toBe(true);
+  });
+
+  it('returns false when paused', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    pauseAudioChannel(channel!);
+    expect(isAudioChannelPlaying(channel!)).toBe(false);
+  });
+});
+
+describe('pauseAudioChannel', () => {
+  it('preserves playback position and marks the channel as paused', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()), { currentTime: 100 });
+    expect(channel).not.toBeNull();
+    pauseAudioChannel(channel!);
+    expect(channel!.currentTime).toBe(100);
+    expect(channel!.state).toBe('paused');
+  });
+});
+
+describe('playAudioResource', () => {
+  it('returns null when buffer is null', () => {
+    const source = createAudioResource();
+    expect(playAudioResource(ctx, source)).toBeNull();
+  });
+
+  it('returns a playing channel when buffer is available', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()), { gain: 0.5 });
+    expect(channel).not.toBeNull();
+    expect(channel!.gain).toBe(0.5);
+    expect(channel!.state).toBe('playing');
+  });
+});
+
+describe('resumeAudioChannel', () => {
+  it('restarts playback from a paused channel', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    pauseAudioChannel(channel!);
+    resumeAudioChannel(channel!);
+    expect(channel!.state).toBe('playing');
+  });
+});
+
+describe('setAudioChannelCurrentTime', () => {
+  it('updates and clamps the channel current time', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    expect(setAudioChannelCurrentTime(channel!, 2000)).toBe(1000);
+  });
+});
+
+describe('setAudioChannelGain', () => {
+  it('updates the channel gain', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    expect(setAudioChannelGain(channel!, 0.25)).toBe(0.25);
+    expect(channel!.gain).toBe(0.25);
+  });
+});
+
+describe('setAudioChannelPlaybackRate', () => {
+  it('updates the channel playback rate', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    expect(setAudioChannelPlaybackRate(channel!, 2)).toBe(2);
+    expect(channel!.playbackRate).toBe(2);
+  });
+});
+
+describe('stopAudioChannel', () => {
+  it('stops playback and resets the current time', () => {
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()), { currentTime: 500 });
+    expect(channel).not.toBeNull();
+    stopAudioChannel(channel!);
+    expect(channel!.currentTime).toBe(0);
+    expect(channel!.state).toBe('stopped');
+  });
+});

package/src/audioMixer.test.ts

@@ -0,0 +1,281 @@
+import { createAudioResource } from '@flighthq/audio';
+
+import { playAudioResource } from './audioChannel';
+import {
+  addAudioBusToMixer,
+  createAudioBus,
+  createAudioMixer,
+  destroyAudioMixer,
+  fadeAudioBusGain,
+  getAudioMixerActiveChannels,
+  pauseAllAudioMixerChannels,
+  resumeAllAudioMixerChannels,
+  routeAudioChannelToMixerBus,
+  setAudioBusGain,
+  setAudioBusMuted,
+  setAudioBusPan,
+  setAudioMixerMasterGain,
+  setAudioMixerMasterMuted,
+  stopAllAudioMixerChannels,
+  unrouteAudioChannelFromMixerBus,
+} from './audioMixer';
+
+const createdSourceNodes: MockAudioBufferSourceNode[] = [];
+
+class MockStereoPannerNode {
+  pan = { value: 0 };
+  connect(): void {}
+  disconnect(): void {}
+}
+
+class MockAudioBufferSourceNode {
+  buffer: AudioBuffer | null = null;
+  loopEnd = 0;
+  loopStart = 0;
+  onended: (() => void) | null = null;
+  playbackRate = { value: 1 };
+  stopCount = 0;
+  connect(): void {}
+  start(): void {}
+  stop(): void {
+    this.stopCount++;
+  }
+}
+
+class MockGainNode {
+  gain = {
+    cancelScheduledValues: () => {},
+    linearRampToValueAtTime: () => {},
+    setValueAtTime: () => {},
+    value: 1,
+  };
+  connect(): void {}
+  disconnect(): void {}
+}
+
+class MockAudioContext {
+  currentTime = 0;
+  destination = {};
+  state = 'running';
+  createBufferSource(): AudioBufferSourceNode {
+    const node = new MockAudioBufferSourceNode();
+    createdSourceNodes.push(node);
+    return node as unknown as AudioBufferSourceNode;
+  }
+  createGain(): GainNode {
+    return new MockGainNode() as unknown as GainNode;
+  }
+  createStereoPanner(): StereoPannerNode {
+    return new MockStereoPannerNode() as unknown as StereoPannerNode;
+  }
+  resume(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+const ctx = new MockAudioContext() as unknown as AudioContext;
+
+function createMockAudioBuffer(): AudioBuffer {
+  return { duration: 1 } as AudioBuffer;
+}
+
+describe('addAudioBusToMixer', () => {
+  it('registers the bus in the Web Audio graph without error', () => {
+    const mixer = createAudioMixer(ctx);
+    const bus = createAudioBus({ name: 'sfx', gain: 0.8 });
+    expect(() => addAudioBusToMixer(mixer, bus)).not.toThrow();
+  });
+
+  it('is idempotent — calling twice does not duplicate the bus', () => {
+    const mixer = createAudioMixer(ctx);
+    const bus = createAudioBus({ name: 'music' });
+    addAudioBusToMixer(mixer, bus);
+    expect(() => addAudioBusToMixer(mixer, bus)).not.toThrow();
+  });
+});
+
+describe('createAudioBus', () => {
+  it('creates a bus with default values', () => {
+    const bus = createAudioBus();
+    expect(bus.gain).toBe(1);
+    expect(bus.muted).toBe(false);
+    expect(bus.name).toBe('');
+    expect(bus.pan).toBe(0);
+  });
+
+  it('creates a bus with provided options', () => {
+    const bus = createAudioBus({ gain: 0.7, muted: true, name: 'sfx', pan: 0.3 });
+    expect(bus.gain).toBe(0.7);
+    expect(bus.muted).toBe(true);
+    expect(bus.name).toBe('sfx');
+    expect(bus.pan).toBe(0.3);
+  });
+});
+
+describe('createAudioMixer', () => {
+  it('creates a mixer with default master values', () => {
+    const mixer = createAudioMixer(ctx);
+    expect(mixer.masterGain).toBe(1);
+    expect(mixer.masterMuted).toBe(false);
+  });
+
+  it('creates a mixer with provided options', () => {
+    const mixer = createAudioMixer(ctx, { masterGain: 0.5, masterMuted: true });
+    expect(mixer.masterGain).toBe(0.5);
+    expect(mixer.masterMuted).toBe(true);
+  });
+});
+
+describe('destroyAudioMixer', () => {
+  it('stops routed channels, clears the active set, and is safe to call twice', () => {
+    const mixer = createAudioMixer(ctx);
+    const bus = createAudioBus();
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    routeAudioChannelToMixerBus(mixer, channel!, bus);
+    destroyAudioMixer(mixer);
+    expect(channel!.state).toBe('stopped');
+    expect(getAudioMixerActiveChannels(mixer)).toHaveLength(0);
+    expect(() => destroyAudioMixer(mixer)).not.toThrow();
+  });
+});
+
+describe('fadeAudioBusGain', () => {
+  it('updates bus gain immediately when no audio context time has passed', () => {
+    const mixer = createAudioMixer(ctx);
+    const bus = createAudioBus({ gain: 1 });
+    addAudioBusToMixer(mixer, bus);
+    fadeAudioBusGain(mixer, bus, 0.5, 500);
+    expect(bus.gain).toBe(0.5);
+  });
+
+  it('updates bus gain data when bus is not in a mixer', () => {
+    const mixer = createAudioMixer(ctx);
+    const bus = createAudioBus({ gain: 1 });
+    fadeAudioBusGain(mixer, bus, 0.3, 200);
+    expect(bus.gain).toBe(0.3);
+  });
+});
+
+describe('getAudioMixerActiveChannels', () => {
+  it('returns an empty array for a new mixer', () => {
+    const mixer = createAudioMixer(ctx);
+    expect(getAudioMixerActiveChannels(mixer)).toHaveLength(0);
+  });
+
+  it('returns routed channels', () => {
+    const mixer = createAudioMixer(ctx);
+    const bus = createAudioBus();
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    routeAudioChannelToMixerBus(mixer, channel!, bus);
+    expect(getAudioMixerActiveChannels(mixer)).toHaveLength(1);
+  });
+});
+
+describe('pauseAllAudioMixerChannels', () => {
+  it('stops the source node and marks playing channels as paused', () => {
+    createdSourceNodes.length = 0;
+    const mixer = createAudioMixer(ctx);
+    const bus = createAudioBus();
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    routeAudioChannelToMixerBus(mixer, channel!, bus);
+    pauseAllAudioMixerChannels(mixer);
+    expect(channel!.state).toBe('paused');
+    expect(createdSourceNodes[0]?.stopCount).toBeGreaterThan(0);
+  });
+});
+
+describe('resumeAllAudioMixerChannels', () => {
+  it('restarts the source node and marks paused channels as playing', () => {
+    createdSourceNodes.length = 0;
+    const mixer = createAudioMixer(ctx);
+    const bus = createAudioBus();
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    routeAudioChannelToMixerBus(mixer, channel!, bus);
+    pauseAllAudioMixerChannels(mixer);
+    resumeAllAudioMixerChannels(mixer);
+    expect(channel!.state).toBe('playing');
+    // A fresh source node is created on resume (the paused one was stopped and discarded).
+    expect(createdSourceNodes.length).toBeGreaterThan(1);
+  });
+});
+
+describe('routeAudioChannelToMixerBus', () => {
+  it('adds the channel to the mixer active channels', () => {
+    const mixer = createAudioMixer(ctx);
+    const bus = createAudioBus();
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    routeAudioChannelToMixerBus(mixer, channel!, bus);
+    expect(getAudioMixerActiveChannels(mixer)).toContain(channel!);
+  });
+});
+
+describe('setAudioBusGain', () => {
+  it('updates bus gain', () => {
+    const bus = createAudioBus();
+    expect(setAudioBusGain(bus, 0.5)).toBe(0.5);
+    expect(bus.gain).toBe(0.5);
+  });
+});
+
+describe('setAudioBusMuted', () => {
+  it('mutes the bus', () => {
+    const bus = createAudioBus();
+    expect(setAudioBusMuted(bus, true)).toBe(true);
+    expect(bus.muted).toBe(true);
+  });
+});
+
+describe('setAudioBusPan', () => {
+  it('sets bus pan and clamps to [-1, 1]', () => {
+    const bus = createAudioBus();
+    expect(setAudioBusPan(bus, 0.5)).toBe(0.5);
+    expect(setAudioBusPan(bus, 2)).toBe(1);
+    expect(setAudioBusPan(bus, -2)).toBe(-1);
+  });
+});
+
+describe('setAudioMixerMasterGain', () => {
+  it('updates the master gain', () => {
+    const mixer = createAudioMixer(ctx);
+    expect(setAudioMixerMasterGain(mixer, 0.5)).toBe(0.5);
+    expect(mixer.masterGain).toBe(0.5);
+  });
+});
+
+describe('setAudioMixerMasterMuted', () => {
+  it('mutes the master', () => {
+    const mixer = createAudioMixer(ctx);
+    expect(setAudioMixerMasterMuted(mixer, true)).toBe(true);
+    expect(mixer.masterMuted).toBe(true);
+  });
+});
+
+describe('stopAllAudioMixerChannels', () => {
+  it('stops all routed channels and clears the active set', () => {
+    const mixer = createAudioMixer(ctx);
+    const bus = createAudioBus();
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    routeAudioChannelToMixerBus(mixer, channel!, bus);
+    stopAllAudioMixerChannels(mixer);
+    expect(channel!.state).toBe('stopped');
+    expect(getAudioMixerActiveChannels(mixer)).toHaveLength(0);
+  });
+});
+
+describe('unrouteAudioChannelFromMixerBus', () => {
+  it('removes the channel from the mixer active channels', () => {
+    const mixer = createAudioMixer(ctx);
+    const bus = createAudioBus();
+    const channel = playAudioResource(ctx, createAudioResource(createMockAudioBuffer()));
+    expect(channel).not.toBeNull();
+    routeAudioChannelToMixerBus(mixer, channel!, bus);
+    unrouteAudioChannelFromMixerBus(mixer, channel!);
+    expect(getAudioMixerActiveChannels(mixer)).toHaveLength(0);
+  });
+});