sound_observation.h File Reference

Audio observation operator for mapping field measurements to audio controls. More...

#include "oakfield/operator_split.h"
#include <stdbool.h>
#include <stddef.h>

Include dependency graph for sound_observation.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	SimSoundObservationConfig
	Configuration for sound observation and audio-control extraction. More...
struct	SimSoundObservationTap
	Latest sound-control values produced by an observation operator. More...

Typedefs
typedef enum SimSoundTranslationSource	SimSoundTranslationSource
	Field-derived source used to drive a sound control.
typedef enum SimSoundModulatorSource	SimSoundModulatorSource
	Optional modulation source for a translated control.
typedef enum SimSoundSamplingMode	SimSoundSamplingMode
	Reduction used when sampling a field for sound observation.
typedef enum SimSoundSamplingDomain	SimSoundSamplingDomain
	Domain sampled by the observer.
typedef enum SimSoundWindowType	SimSoundWindowType
	Window function applied to multi-sample reductions.
typedef enum SimSoundPanLaw	SimSoundPanLaw
	Mapping from pan control value to channel gains.
typedef enum SimSoundPitchScale	SimSoundPitchScale
	Pitch-control scale used to derive output frequency.
typedef enum SimSoundOutputMode	SimSoundOutputMode
	Output representation produced by the observation operator.
typedef enum SimSoundRawSampleSource	SimSoundRawSampleSource
	Component sampled when emitting raw audio samples.
typedef enum SimSoundRawChannelMode	SimSoundRawChannelMode
	Channel layout used for raw audio sample output.
typedef enum SimSoundResampleMode	SimSoundResampleMode
	Resampling kernel for converting field samples to raw audio samples.
typedef struct SimSoundObservationConfig	SimSoundObservationConfig
	Configuration for sound observation and audio-control extraction.
typedef struct SimSoundObservationTap	SimSoundObservationTap
	Latest sound-control values produced by an observation operator.

Enumerations
enum	SimSoundTranslationSource {   SIM_SOUND_TRANSLATION_SOURCE_OFF = 0 , SIM_SOUND_TRANSLATION_SOURCE_AMPLITUDE , SIM_SOUND_TRANSLATION_SOURCE_PHASE , SIM_SOUND_TRANSLATION_SOURCE_SPECTRAL_CENTROID ,   SIM_SOUND_TRANSLATION_SOURCE_FIELD }
	Field-derived source used to drive a sound control. More...
enum	SimSoundModulatorSource { SIM_SOUND_MODULATOR_NONE = 0 , SIM_SOUND_MODULATOR_SELF_FIELD , SIM_SOUND_MODULATOR_EXTERNAL_FIELD }
	Optional modulation source for a translated control. More...
enum	SimSoundSamplingMode {   SIM_SOUND_SAMPLING_POINT = 0 , SIM_SOUND_SAMPLING_MEAN , SIM_SOUND_SAMPLING_RMS , SIM_SOUND_SAMPLING_PEAK ,   SIM_SOUND_SAMPLING_ABS_MEAN , SIM_SOUND_SAMPLING_ABS_PEAK , SIM_SOUND_SAMPLING_WINDOWED_RMS }
	Reduction used when sampling a field for sound observation. More...
enum	SimSoundSamplingDomain { SIM_SOUND_SAMPLING_DOMAIN_PHYSICAL = 0 , SIM_SOUND_SAMPLING_DOMAIN_SPECTRAL }
	Domain sampled by the observer. More...
enum	SimSoundWindowType {   SIM_SOUND_WINDOW_RECT = 0 , SIM_SOUND_WINDOW_HANN , SIM_SOUND_WINDOW_HAMMING , SIM_SOUND_WINDOW_BLACKMAN ,   SIM_SOUND_WINDOW_KAISER }
	Window function applied to multi-sample reductions. More...
enum	SimSoundPanLaw { SIM_SOUND_PAN_LAW_LINEAR = 0 , SIM_SOUND_PAN_LAW_EQUAL_POWER }
	Mapping from pan control value to channel gains. More...
enum	SimSoundPitchScale { SIM_SOUND_PITCH_SCALE_LINEAR_HZ = 0 , SIM_SOUND_PITCH_SCALE_LOG2_HZ , SIM_SOUND_PITCH_SCALE_MIDI }
	Pitch-control scale used to derive output frequency. More...
enum	SimSoundOutputMode { SIM_SOUND_OUTPUT_CONTROLS = 0 , SIM_SOUND_OUTPUT_RAW_SAMPLES }
	Output representation produced by the observation operator. More...
enum	SimSoundRawSampleSource { SIM_SOUND_RAW_SOURCE_REAL = 0 , SIM_SOUND_RAW_SOURCE_IMAG , SIM_SOUND_RAW_SOURCE_MAGNITUDE , SIM_SOUND_RAW_SOURCE_PHASE }
	Component sampled when emitting raw audio samples. More...
enum	SimSoundRawChannelMode { SIM_SOUND_RAW_CHANNEL_MONO = 0 , SIM_SOUND_RAW_CHANNEL_STEREO_DUPLICATE , SIM_SOUND_RAW_CHANNEL_STEREO_REAL_IMAG }
	Channel layout used for raw audio sample output. More...
enum	SimSoundResampleMode { SIM_SOUND_RESAMPLE_NEAREST = 0 , SIM_SOUND_RESAMPLE_LINEAR , SIM_SOUND_RESAMPLE_CUBIC }
	Resampling kernel for converting field samples to raw audio samples. More...

Functions
SimResult	sim_add_sound_observation_operator (struct SimContext *context, const SimSoundObservationConfig *config, size_t *out_index)
	Register a sound observation operator.
SimResult	sim_sound_observation_config (struct SimContext *context, size_t operator_index, SimSoundObservationConfig *out_config)
	Copy the current sound observation configuration from a registered operator.
SimResult	sim_sound_observation_update (struct SimContext *context, size_t operator_index, const SimSoundObservationConfig *config)
	Replace or renormalize a registered sound observation configuration.
SimResult	sim_sound_observation_tap (struct SimContext *context, size_t operator_index, SimSoundObservationTap *out_tap)
	Copy the latest sound-control tap from a registered observer.

Detailed Description

Audio observation operator for mapping field measurements to audio controls.

Enumeration Type Documentation

SimSoundModulatorSource

enum SimSoundModulatorSource

Optional modulation source for a translated control.

Enumerator
SIM_SOUND_MODULATOR_NONE	No modulation source.
SIM_SOUND_MODULATOR_SELF_FIELD	Modulate from the observed field.
SIM_SOUND_MODULATOR_EXTERNAL_FIELD	Modulate from the configured modulator field.

SimSoundOutputMode

enum SimSoundOutputMode

Output representation produced by the observation operator.

Enumerator
SIM_SOUND_OUTPUT_CONTROLS	Emit derived audio-control values.
SIM_SOUND_OUTPUT_RAW_SAMPLES	Emit raw sampled audio frames.

SimSoundPanLaw

enum SimSoundPanLaw

Mapping from pan control value to channel gains.

Enumerator
SIM_SOUND_PAN_LAW_LINEAR	Linear pan gain law.
SIM_SOUND_PAN_LAW_EQUAL_POWER	Equal-power pan gain law.

SimSoundPitchScale

enum SimSoundPitchScale

Pitch-control scale used to derive output frequency.

Enumerator
SIM_SOUND_PITCH_SCALE_LINEAR_HZ	Interpret pitch linearly in hertz.
SIM_SOUND_PITCH_SCALE_LOG2_HZ	Interpret pitch logarithmically base 2.
SIM_SOUND_PITCH_SCALE_MIDI	Interpret pitch using MIDI note semantics.

SimSoundRawChannelMode

enum SimSoundRawChannelMode

Channel layout used for raw audio sample output.

Enumerator
SIM_SOUND_RAW_CHANNEL_MONO	Emit one mono channel.
SIM_SOUND_RAW_CHANNEL_STEREO_DUPLICATE	Duplicate mono samples to stereo.
SIM_SOUND_RAW_CHANNEL_STEREO_REAL_IMAG	Emit real/imaginary as stereo channels.

SimSoundRawSampleSource

enum SimSoundRawSampleSource

Component sampled when emitting raw audio samples.

Enumerator
SIM_SOUND_RAW_SOURCE_REAL	Emit real component.
SIM_SOUND_RAW_SOURCE_IMAG	Emit imaginary component.
SIM_SOUND_RAW_SOURCE_MAGNITUDE	Emit magnitude.
SIM_SOUND_RAW_SOURCE_PHASE	Emit phase.

SimSoundResampleMode

enum SimSoundResampleMode

Resampling kernel for converting field samples to raw audio samples.

Enumerator
SIM_SOUND_RESAMPLE_NEAREST	Nearest-neighbor resampling.
SIM_SOUND_RESAMPLE_LINEAR	Linear resampling.
SIM_SOUND_RESAMPLE_CUBIC	Cubic resampling.

SimSoundSamplingDomain

enum SimSoundSamplingDomain

Domain sampled by the observer.

Enumerator
SIM_SOUND_SAMPLING_DOMAIN_PHYSICAL	Sample the physical-domain field.
SIM_SOUND_SAMPLING_DOMAIN_SPECTRAL	Sample spectral-domain values.

SimSoundSamplingMode

enum SimSoundSamplingMode

Reduction used when sampling a field for sound observation.

Enumerator
SIM_SOUND_SAMPLING_POINT	Sample one point.
SIM_SOUND_SAMPLING_MEAN	Mean over the selected samples.
SIM_SOUND_SAMPLING_RMS	Root-mean-square over selected samples.
SIM_SOUND_SAMPLING_PEAK	Signed peak over selected samples.
SIM_SOUND_SAMPLING_ABS_MEAN	Mean absolute value over selected samples.
SIM_SOUND_SAMPLING_ABS_PEAK	Peak absolute value over selected samples.
SIM_SOUND_SAMPLING_WINDOWED_RMS	Windowed root-mean-square over selected samples.

SimSoundTranslationSource

enum SimSoundTranslationSource

Field-derived source used to drive a sound control.

Enumerator
SIM_SOUND_TRANSLATION_SOURCE_OFF	Control source disabled.
SIM_SOUND_TRANSLATION_SOURCE_AMPLITUDE	Use field amplitude.
SIM_SOUND_TRANSLATION_SOURCE_PHASE	Use field phase.
SIM_SOUND_TRANSLATION_SOURCE_SPECTRAL_CENTROID	Use spectral centroid estimate.
SIM_SOUND_TRANSLATION_SOURCE_FIELD	Use raw sampled field value.

SimSoundWindowType

enum SimSoundWindowType

Window function applied to multi-sample reductions.

Enumerator
SIM_SOUND_WINDOW_RECT	Rectangular window.
SIM_SOUND_WINDOW_HANN	Hann window.
SIM_SOUND_WINDOW_HAMMING	Hamming window.
SIM_SOUND_WINDOW_BLACKMAN	Blackman window.
SIM_SOUND_WINDOW_KAISER	Kaiser window.

Function Documentation

sim_add_sound_observation_operator()

SimResult sim_add_sound_observation_operator	(	struct SimContext *	context,
		const SimSoundObservationConfig *	config,
		size_t *	out_index
	)

Register a sound observation operator.

The operator samples a field into audio-control taps or raw sample output according to the configured sampling, modulation, and smoothing modes.

Parameters

	context	Simulation context that will own the operator.
	config	Optional sound observation configuration; NULL selects normalized defaults.
[out]	out_index	Optional destination for the registered operator index.

Returns

SIM_RESULT_OK on success, or an error code from argument validation, field validation, allocation, or split registration.

sim_sound_observation_config()

SimResult sim_sound_observation_config	(	struct SimContext *	context,
		size_t	operator_index,
		SimSoundObservationConfig *	out_config
	)

Copy the current sound observation configuration from a registered operator.

Parameters

	context	Simulation context containing the operator.
	operator_index	Index returned by sim_add_sound_observation_operator().
[out]	out_config	Receives the normalized configuration.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for NULL pointers, SIM_RESULT_NOT_FOUND for a missing operator, or SIM_RESULT_INVALID_STATE when the operator has no sound state.

sim_sound_observation_tap()

SimResult sim_sound_observation_tap	(	struct SimContext *	context,
		size_t	operator_index,
		SimSoundObservationTap *	out_tap
	)

Copy the latest sound-control tap from a registered observer.

Parameters

	context	Simulation context containing the operator.
	operator_index	Index returned by sim_add_sound_observation_operator().
[out]	out_tap	Receives the latest tap snapshot.

Returns

SIM_RESULT_OK on success, SIM_RESULT_INVALID_ARGUMENT for NULL pointers, SIM_RESULT_NOT_FOUND for a missing operator, or SIM_RESULT_INVALID_STATE when the operator has no sound state.

sim_sound_observation_update()

SimResult sim_sound_observation_update	(	struct SimContext *	context,
		size_t	operator_index,
		const SimSoundObservationConfig *	config
	)

Replace or renormalize a registered sound observation configuration.

Passing NULL for config keeps the current configuration and reapplies normalization. A successful update refreshes runtime state and invalidates the scheduler plan.

Parameters

context	Simulation context containing the operator.
operator_index	Index of the sound observation operator to update.
config	Optional replacement configuration.

Returns

SIM_RESULT_OK on success, or an error code from lookup, field validation, allocation, or state validation.