# AudioMusicHandle

> Talos 0.6 · Since 0.6

The score.

Layers change on a bar line, never mid-phrase.

## Signature

```ts
export interface AudioMusicHandle {
  /**
   * Queue a layer from `meta.audio.music.layers`. The cross-fade begins at the next bar,
   * so the change lands on the beat. Returns the voice handle it will sound on, usable
   * with {@link AudioHandle.stop}, or 0 when the scene has no such layer.
   */
  play(layer: string, opts?: MusicOptions): number
}
```

Import: `import type { AudioMusicHandle } from "@argus/api"`

## Members

| Member | Signature | Description |
|---|---|---|
| `play` | `play(layer: string, opts?: MusicOptions): number` | Queue a layer from `meta.audio.music.layers`. The cross-fade begins at the next bar, so the change lands on the beat. Returns the voice handle it will sound on, usable with {@link AudioHandle.stop}, or 0 when the scene has no such layer. |

## Example

The tested fixture `fixtures/host/door.ts`.

```ts
import type { Behavior } from "@argus/api"
// docs/API.md, "Joints": a door on a hinge that swings open while the player is near and closes
// behind them. Typechecked by packages/api's tests.
export default {
  update(ctx) {
    const player = ctx.world.find("player")
    const near = player !== null && ctx.entity.distanceTo(player) < 2
    ctx.joint?.setMotor(near ? Math.PI / 2 : 0, { mode: "position", maxForce: 200 })
  },
} satisfies Behavior
```