# API

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

## Sound {#sound}

### createListener {#createlistener}

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

interface ListenerOptions {
  output?: AudioNode;
  tile?: number;
  world?: World;
  params?: Partial;
  materials?: Record;
  reverbs?: Record;
  pos(): Point;
}

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

`voice` was added in 0.2. See [Listeners](./sound#listeners).

### World {#world}

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

Points are in tiles.

### Source {#source}

```ts
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 {#point-material-reverb-params}

```ts
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 {#defaults}

```ts
const DEFAULT_PARAMS: Readonly;
const DEFAULT_MATERIALS: Readonly>;
const DEFAULT_REVERBS: Readonly>;
```

The values are in [Params](./sound#params), [Materials](./sound#materials) and [Reverbs](./sound#reverbs).

### wallsOnGrid {#wallsongrid}

```ts
function wallsOnGrid(tiles: ReadonlyArray>, a: Point, b: Point): string[];
```

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

### wallsAlong {#wallsalong}

Added in 0.3.

```ts
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 {#distancegain}

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

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

### computeMix and Mix {#computemix}

```ts
function computeMix(
  listener: Point,
  source: Point,
  walls: readonly string[],
  params: Params,
  materials: Readonly>,
): 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 {#loudness}

### createLoudness {#createloudness}

```ts
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;
  recalibrate(): Promise;
  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](./loudness).

### createLevelDetector {#createleveldetector}

```ts
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 {#hearddb}

```ts
function heardDb(level: number, mix: Pick, levelDb?: readonly number[]): number;
```

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

## Voice {#voice}

All added in 0.2. See [Voice](./voice).

### Voice type {#voice-type}

```ts
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 {#createvoicemic}

```ts
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;
  stop(): void;
}
```

### createRoomCode {#createroomcode}

```ts
function createRoomCode(): string;
```

128 random bits in URL-safe base64.

### joinVoiceRoom {#joinvoiceroom}

```ts
function joinVoiceRoom(options: VoiceRoomOptions): Promise;

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;
  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](./voice#connections-and-errors).

## Further reading {#further-reading}

- [Earshot 0.2: voice chat that hears your walls](/blog/earshot-sound-through-walls)
- [What a game wall does to sound, measured in Web Audio](/research/what-a-wall-does-to-sound)