API

Every export of @debuffjp/earshot at 0.3.0. Anything not marked has been there since before 0.2.

Sound

createListener

function createListener(ctx: BaseAudioContext, options: ListenerOptions): Listener;

interface ListenerOptions {
  output?: AudioNode;
  tile?: number;
  world?: World;
  params?: Partial<Params>;
  materials?: Record<string, Material>;
  reverbs?: Record<string, Reverb>;
  pos(): Point;
}

interface Listener {
  readonly params: Params;
  readonly materials: Record<string, Material>;
  readonly reverbs: Record<string, Reverb>;
  source(input: AudioNode, options: SourceOptions): Source;
  voice(stream: MediaStream, options: VoiceOptions): Voice;
  update(): void;
  dispose(): void;
}

voice was added in 0.2. See Listeners.

World

interface World {
  wallsBetween?(a: Point, b: Point): readonly string[];
  reverbAt?(p: Point): string | null | undefined;
}

Points are in tiles.

Source

interface SourceOptions { pos(): Point }

type SourceState = "audible" | "out-of-range" | "muted";

interface Source {
  readonly state: SourceState;
  readonly mix: Mix | null;
  readonly reverb: string | null;
  muted: boolean;
  remove(): void;
}

Changed in 0.3: a new source starts at its mix instead of fading in.

Point, Material, Reverb, Params

interface Point { x: number; y: number }
interface Material { hz: number; db: number }
interface Reverb { seconds: number; wetDb: number }

interface Params {
  fullRadius: number;
  silentRadius: number;
  panWidth: number;
  panRange: number;
  smoothing: number;
  multiWall: Material;
}

Defaults

const DEFAULT_PARAMS: Readonly<Params>;
const DEFAULT_MATERIALS: Readonly<Record<string, Material>>;
const DEFAULT_REVERBS: Readonly<Record<string, Reverb>>;

The values are in Params, Materials and Reverbs.

wallsOnGrid

function wallsOnGrid(tiles: ReadonlyArray<ReadonlyArray<string | null | undefined>>, a: Point, b: Point): string[];

Walls crossed between two points in tiles. tiles[y][x] holds a material name or nothing.

wallsAlong

Added in 0.3.

function wallsAlong(at: (x: number, y: number) => string | null | undefined, a: Point, b: Point): string[];

Like wallsOnGrid, for maps that aren't nested arrays.

distanceGain

function distanceGain(d: number, full: number, silent: number): number;

1 inside full, exactly 0 from silent on, smoothstep between.

computeMix and Mix

function computeMix(
  listener: Point,
  source: Point,
  walls: readonly string[],
  params: Params,
  materials: Readonly<Record<string, Material>>,
): Mix;

interface Mix {
  distance: number;
  gain: number;
  cutoff: number;
  pan: number;
  walls: readonly string[];
}

The whole decision as plain numbers. Points are in tiles. Throws on a single wall with an unknown material.

Loudness

createLoudness

function createLoudness(ctx: AudioContext, options?: LoudnessOptions): Loudness;

interface LoudnessOptions extends DetectorOptions {
  calibrateMs?: number;
  browserProcessing?: boolean;
}

interface Loudness {
  readonly level: LoudLevel;
  readonly micStatus: MicStatus;
  readonly overFloorDb: number | null;
  readonly applied: MediaTrackSettings | null;
  press(level: LoudLevel): void;
  enableMic(): Promise<MicResult>;
  recalibrate(): Promise<void>;
  disableMic(): void;
  onLevel(callback: (level: LoudLevel) => void): () => void;
}

type LoudLevel = 0 | 1 | 2 | 3;
type MicStatus = "off" | "calibrating" | "on";
interface MicResult { ok: boolean; error?: string }

See Loudness.

createLevelDetector

function createLevelDetector(options?: DetectorOptions): LevelDetector;

interface DetectorOptions {
  steps?: readonly [number, number, number];
  attackMs?: number;
  releaseMs?: number;
  hysteresisDb?: number;
}

interface LevelDetector {
  readonly floor: number | null;
  readonly level: LoudLevel;
  calibrate(readings: readonly number[]): void;
  update(db: number, dtMs: number): LoudLevel;
}

heardDb

function heardDb(level: number, mix: Pick<Mix, "gain">, levelDb?: readonly number[]): number;

How loud a noise is at a point, in dB. levelDb defaults to [-Infinity, 10, 20, 30].

Voice

All added in 0.2. See Voice.

Voice type

interface VoiceOptions extends SourceOptions { speakingDb?: number }

interface Voice extends Source {
  readonly levelDb: number;
  readonly speaking: boolean;
}

Returned by listener.voice(), which throws on an OfflineAudioContext.

createVoiceMic

function createVoiceMic(options: VoiceMicOptions): VoiceMic;

interface VoiceMicOptions {
  canUseVoice(): boolean;
  echoCancellation?: boolean | "all" | "remote-only";
  pushToTalk?: boolean;
}

interface VoiceMic {
  readonly stream: MediaStream | null;
  readonly applied: MediaTrackSettings | null;
  readonly live: boolean;
  muted: boolean;
  pushToTalk: boolean;
  talk(held: boolean): void;
  start(): Promise<MicResult>;
  stop(): void;
}

createRoomCode

function createRoomCode(): string;

128 random bits in URL-safe base64.

joinVoiceRoom

function joinVoiceRoom(options: VoiceRoomOptions): Promise<JoinResult>;

interface VoiceRoomOptions {
  url: string;
  code: string;
  mic: VoiceMic;
  listener: Listener;
  ipPolicy: "relay" | "direct";
  pos(peer: string): Point;
  onPeer?(peer: string, voice: Voice): void;
  onLeave?(peer: string): void;
  onMessage?(peer: string, message: unknown): void;
}

interface VoiceRoom {
  readonly id: string;
  readonly peers: ReadonlyMap<string, Voice>;
  connection(peer: string): RTCPeerConnectionState | null;
  send(message: unknown): void;
  leave(): void;
}

type JoinResult = { ok: true; room: VoiceRoom } | (MicResult & { ok: false; error: string });

Never rejects. See Connections and errors.

Further reading

• Earshot 0.2: voice chat that hears your walls
• What a game wall does to sound, measured in Web Audio