Especificaciones
Guía técnica de funcionamiento y restricciones del sistema de audio
Esta sección documenta el comportamiento efectivo del sistema en ejecución. No define contratos de API, sino que describe qué parámetros permanecen fijos, cuáles pueden negociarse y en qué capas se toman las decisiones relevantes.
Backend
Adaptador (CoreAudio, WASAPI, ALSA)
Compatibilidad
Linux, Windows y macOS. Mobile: Android e iOS.
Modo de Render (pull/push)
Modelo Híbrido: el backend entrega callbacks push, mientras que el grafo interno se resuelve mediante pull.
Enrutamiento de Audio
Render (salida), Record (entrada) y Duplex. Si la ruta solicitada no está disponible, el sistema fuerza el uso de render.
Sample Rate
Utilización de canonicalSampleRate fijo en 44.100 Hz. No existe negociación dinámica con el dispositivo ni resampling en la ruta principal.
Profundidad de Bits
32-bit floating point (Float32). El stream del backend y la representación interna del motor coinciden.
Formato de muestreo
Float32 (Scalar = Float32). No se realiza conversión de formato de muestra en ninguna etapa del pipeline.
Cantidad de canales (salida)
Soporte explícito para mono y estéreo; valores >2 no están implementados en el motor.
Cantidad de canales (entrada)
En modos record/duplex, el input efectivo al grafo es mono; no se realiza deinterleaving multicanal. AudioGraph soporta únicamente input mono.
Layout de buffers
Internamente planar (un AudioBus por canal). La salida al backend es interleaved; la entrada desde backend se trata como buffer lineal.
Parámetros fijos/negociados
Fijos: sample rate, formato Float32 y Quantum interno. Negociado: categoría de dispositivo (render/record/duplex) según disponibilidad.
Solicitud/Efectivos
Una solicitud de duplex puede degradarse a render si no hay captura disponible; el input no se entrega si no es mono.
Representación numérica
Audio en Float32; control y tiempo en Float64. El procesamiento DSP y los buses de audio operan en Float32.
Conversiones
No existe conversión de formato; únicamente interleaving de planar a interleaved en la salida, entregando Float32 interleaved al backend.
Punto de Conversión
El interleaving se realiza en HardwareIO; la conversión de layout no ocurre dentro del grafo de audio.
Quantum efectivo (frames)
Uso de canonicalQuantum = .adaptive (256) en hardware real y .balanced (512) en simulador. El Quantum es fijo para el grafo y depende de targetEnvironment.
Variabilidad del Quantum
El grafo interno opera con Quantum fijo; el callback del backend puede entregar un frameCount distinto que se reagrupa a renderQuantum por acumulación.
Buffer Size (Backend)
Se rellena el frameCount del backend iterando bloques de renderQuantum hasta consumir los frames restantes; un callback puede abarcar múltiples bloques o un bloque parcial.
Periodicidad del Callback
Definida por el backend, el motor interno opera a 256 frames (~5,80 ms) o 512 frames (~11,61 ms) a 44.100 Hz.
Buffering adicional
Ring buffer de entrada (_unprocessedSource) con capacidad aproximada de 4 s; buffers _source y _rendering por quantum. En record o duplex, el input se acumula.
Impacto contractual del Quantum
frameCount debe ser potencia de dos para el panner binaural; el canonicalQuantum actual (256/512) cumple este requisito. Valores no potencia de dos violan precondiciones.
Fuente de relog principal
Contador de frames junto con canonicalSampleRate; el hardware actualiza lastCursor por bloque renderizado.
Unidad temporal
Frames (Int) y TimeInterval derivados de frame/sampleRate. currentTime y currentSampleFrame se derivan de lastCursor.
Latencia efectiva
Latencias individuales por nodo. La latencia efectiva depende del backend y del quantum.
Remixing de canales
Se realiza mezcla mono↔estéreo cuando existe un desajuste con la interpretación de speakers; ocurre en el bus del grafo, no en el backend.
Conversión de formatos
No se realiza conversión de formato de muestra; únicamente conversión de layout planar → interleaved en la salida.
Especificaciones del sistema binaural
Esta sección describe el comportamiento efectivo del sistema de audio binaural, tal como opera dentro del motor y en integración con el pipeline de render general. No se documenta el modelo matemático ni la implementación interna de los nodos.
Sistema de Coordenadas
Sistema right-handed, documentado en la API.
Orientación/Ejes
Eje X positivo hacia la derecha, eje Y positivo hacia arriba, eje Z positivo hacia atrás; el forward perceptual corresponde a −Z. Valores de Z negativos representan posiciones “frente” al listener.
Convención de Forward Vector
forward = −Z según la documentación; se utiliza listener.forward normalizado y se asume una base ortonormal derivada de forward y up.
Convención de Up Vector
Definido mediante listener.up, utilizado para construir los ejes right y up en computeAngles; vectores no ortogonales se consideran normalizados u ortogonalizados a nivel conceptual.
Unidades de medida
Implícitamente metros; inferida a partir de parámetros como speedOfSound (m/s) y radios interno/externo. No existe conversión explícita.
Origen del sistema
Sistema world-centric; posiciones de source y listener se evalúan en el mismo espacio de coordenadas.
Rol del Listener
Punto acústico de referencia que define posición, orientación, velocidad y parámetros globales (doppler, velocidad del sonido).
Parámetros espaciales
position, forward, up y velocity; doppler y speedOfSound influyen en el cálculo de dopplerRate.
Momento de muestreo
Muestreo por bloque de render (frameCount) durante la ejecución de process / computeAngles.
Relación Source → Listener
Se calcula (source − listener), se normaliza y se obtienen azimuth, elevation y distancia. Si el vector es cero, azimuth y elevation se fijan en 0.
Rango esperado de Valores
Rangos aproximados sugeridos (x/z: −1000…1000, y: −40…1000) sin clamping explícito; valores no finitos generan assertions.
Comportamiento fuera de rango
La elevación se clampa al rango soportado por el HRTF; azimuth fuera de rango puede producir silencio. El clamping depende de BinauralDatabase.
Procesamiento binaural
Procesamiento HRTF mediante convolución FFT, delay lines y crossfade entre kernels, produciendo salida binaural estéreo.
Dominio del Procesamiento
Convolución en dominio de frecuencia (ConvolutionFFT) combinada con etapas temporales de retardo (DelayStage).
Sample Rate esperado
Uso de canonicalSampleRate. BinauralDatabase soporta 44.100 Hz y 48.000 Hz; sample rates no soportados generan assertions al inicializar.
Requisitos de entrada/salida
Entrada mono o estéreo; salida estrictamente estéreo. No existe soporte de salida multicanal binaural.
Suposiciones implícitas
frameCount debe ser potencia de dos y la base binaural debe estar cargada para render en tiempo real; de lo contrario, el nodo puede silenciar o abortar.
Relación binaural ↔ stream
El procesamiento binaural produce un AudioBus estéreo; el hardware puede realizar mezclas adicionales según el layout final.
Conversión previa / posterior
No se realiza conversión de formato de muestra; únicamente conversión de layout planar → interleaved en la salida.
No dudes en contactarnos por cualquier inquietud: [email protected], nuestro equipo estará encantado de ayudarte a resolver cualquier problema y mejorar tu experiencia
Última actualización