---
name: audio_play
kind: function
lang: cpp
domain: gamedev
version: "0.1.0"
purity: impure
signature: "sound_load(Engine&, const char*) -> Sound; sound_play/stop/set_volume/destroy(Sound&); play_sound_oneshot(Engine&, const char*, float)"
description: "Reproduccion de audio sobre fn::audio::Engine: carga sonidos con streaming desde disco (wav/mp3/flac/ogg), play/stop/volumen por sonido, y helper fire-and-forget para one-shots sin handle. Cross-platform via miniaudio. Issue 0072b — runtime gamedev nucleo."
tags: [gamedev, audio, miniaudio]
uses_functions: ["audio_engine_cpp_gamedev"]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: []
example: |
  fn::audio::Engine eng = fn::audio::engine_init();
  fn::audio::Sound bgm = fn::audio::sound_load(eng, "assets/bgm.ogg");
  fn::audio::sound_set_volume(bgm, 0.5f);
  fn::audio::sound_play(bgm);
  // SFX one-shot:
  fn::audio::play_sound_oneshot(eng, "assets/jump.wav");
  // ...
  fn::audio::sound_destroy(bgm);
  fn::audio::engine_shutdown(eng);
tested: false
tests: []
test_file_path: ""
file_path: "cpp/functions/gamedev/audio_play.cpp"
params:
  - name: e
    desc: "Engine inicializado por audio_engine_cpp_gamedev. Si e.ok=false, todas las operaciones son no-op."
  - name: path
    desc: "Ruta al archivo de audio (relativa al cwd o absoluta). Formatos: wav/mp3/flac/ogg via decoders integrados de miniaudio."
  - name: s
    desc: "Sound handle. ok=true tras sound_load exitoso. Operaciones tras destroy son no-op."
  - name: v
    desc: "Volumen 0..1 lineal, multiplicativo con el master del Engine."
  - name: volume
    desc: "Volumen sugerido para play_sound_oneshot (actualmente delega al master via ma_engine_play_sound; reservado para futura implementacion per-instance)."
output: "Sound con impl=ma_sound* y ok=true en sound_load exitoso; ok=false ante cualquier fallo (engine no listo, malloc, decoder). play_sound_oneshot no devuelve handle — el sonido se gestiona internamente por el engine."
---

# audio_play

Reproduccion de audio one-shot y streaming sobre `fn::audio::Engine`. Wrapper minimo de la API `ma_sound` de miniaudio.

## Estructura `Sound`

Handle opaco con `impl` (apunta a `ma_sound`) y `ok` (bool). Gestion explicita: cada `sound_load` requiere `sound_destroy` para liberar (no hay RAII porque mantenemos `-fno-exceptions` y compat con structs trivial).

## Patrones de uso

- **BGM / loops largos:** `sound_load` + `sound_play`. Por defecto miniaudio hace streaming desde disco (no carga todo a memoria).
- **SFX cortos:** `play_sound_oneshot` — fire-and-forget, sin handle, ideal para clicks, jumps, hits.
- **SFX repetidos con control:** `sound_load` + `sound_play` cada vez. Para concurrent voices del mismo sample, considerar `ma_sound_init_copy` (no expuesto aun).

## Notas

- `play_sound_oneshot` recibe `volume` como hint pero actualmente delega al master del engine. Iterar si el caller real lo necesita.
- `sound_load` con `path=NULL` o engine no listo devuelve `Sound{nullptr, false}` — siempre comprobar `ok` antes de operar.