Audio & MIDI (std/audio/) #

#include <std/audio/audio.h>          // devices, streams, the audio callback
#include <std/audio/midi.h>           // MIDI ports, messages, parser
#include <std/audio/audio_convert.h>  // sample-format / layout conversion, std/dsp interop

#include <std/audio/audio.h>
#include <std/math.h>
#include <std/thread.h>
extern int printf(const char* fmt, ...);

struct Tone { double phase; double step; };

// The real-time callback: fill io's output buffer, return AUDIO_CB_CONTINUE.
int render(&AudioIo io, ?&Tone tp) {
    match (tp) {
        case some(t): {
            []float out = io.output_f32();   // frames x channels, interleaved
            for (unsigned int f = 0U; f < io.frames; f = f + 1U) {
                float v = (float)(0.2 * std::sin_d(t.phase));
                out[(unsigned long)f * 2UL] = v;           // bounds-checked
                out[(unsigned long)f * 2UL + 1UL] = v;
                t.phase = t.phase + t.step;
            }
        }
        case null: {}
    }
    return AUDIO_CB_CONTINUE;
}

int main() {
    struct Audio audio = std::Audio::open(AUDIO_API_UNSPECIFIED).unwrap_or(std::Audio::closed());
    for (unsigned int i = 0U; i < audio.device_count(); i = i + 1U) {
        struct AudioDeviceInfo d = audio.device_info(i).unwrap_or(std::AudioDeviceInfo::none());
        printf("[%u] %s: %d out, %d in\n", d.id, d.name, d.output_channels, d.input_channels);
    }
    struct Tone tone;
    tone.phase = 0.0;
    tone.step = 2.0 * 3.141592653589793 * 440.0 / 48000.0;
    struct AudioStreamParams out = std::AudioStreamParams::of(audio.default_output_device(), 2);
    unsigned int frames = 256U;                           // requested; receives the actual size
    struct Result<AudioStream, AudioError> r =
        audio.open_stream((?&AudioStreamParams)&out, null, AUDIO_FORMAT_F32, 48000U, &frames,
                          render, (?&Tone)&tone, null);
    match (r.get_err()) {
        case some(e): { printf("%s\n", e.message); r.drop(); audio.close(); return 1; }
        case null: {}
    }
    struct AudioStream s = r.unwrap_or(std::AudioStream::closed());
    s.start();
    std::thread_sleep_ms(2000UL);                        // two seconds
    s.stop();
    s.close();
    audio.close();
    return 0;
}

#define AUDIO_API_UNSPECIFIED 0      // Audio::open(): the default, then any that works
#define AUDIO_API_ALSA        1
#define AUDIO_API_JACK        2
#define AUDIO_API_COREAUDIO   3
#define AUDIO_API_WASAPI      4
#define AUDIO_API_WEBAUDIO    5
#define AUDIO_API_DUMMY       6

int audio_compiled_apis([]int out);   // this build's APIs, in preference order; returns the count
int audio_api_compiled(int api);
int audio_default_api();                      // see below
const &char audio_api_name(int api);          // "alsa"
const &char audio_api_display_name(int api);  // "ALSA"
int audio_api_by_name(const &char name);      // AUDIO_API_UNSPECIFIED if unknown

struct Audio {
    int    api_id;
    ?&struct AudioHost_ impl;   // std-private; null when closed

    static struct Result<Audio, AudioError> open(int api);   // probes the devices
    static struct Audio closed();

    int  is_open() const;
    int  api() const;
    struct AudioError rescan();                              // re-enumerate (hot-plug)
    unsigned int device_count() const;
    struct Result<AudioDeviceInfo, AudioError> device_info(unsigned int index) const;
    struct Result<AudioDeviceInfo, AudioError> device_by_id(unsigned int id) const;
    unsigned int default_output_device() const;              // ids; AUDIO_DEFAULT_DEVICE (0) if none
    unsigned int default_input_device() const;

    generic<T>
    struct Result<AudioStream, AudioError> open_stream(?&AudioStreamParams output, ?&AudioStreamParams input,
                                                       unsigned int format, unsigned int sample_rate,
                                                       &unsigned int frames,
                                                       fn int(&AudioIo, ?&T) callback, ?&T user,
                                                       ?&AudioStreamOptions opts);
    void close() consume;                                    // streams stay valid
};

struct AudioDeviceInfo {
    unsigned int id;
    char         name[AUDIO_DEVICE_NAME_MAX];
    int          output_channels, input_channels, duplex_channels;
    int          is_default_output, is_default_input;
    unsigned int native_formats;                          // AUDIO_FORMAT_* bits
    unsigned int sample_rates[AUDIO_MAX_SAMPLE_RATES];    // ascending
    int          sample_rate_count;
    unsigned int preferred_sample_rate;

    int supports_rate(unsigned int rate) const;
    static struct AudioDeviceInfo none();                 // for unwrap_or()
};

struct AudioStreamParams {
    unsigned int device;        // AudioDeviceInfo.id or AUDIO_DEFAULT_DEVICE
    int          channels;
    int          first_channel; // offset into the device's channels
    static struct AudioStreamParams of(unsigned int device, int channels);
};

struct AudioStreamOptions {
    unsigned int flags;          // AUDIO_FLAG_*
    unsigned int buffer_count;   // periods the device queues (0 = the API's default)
    int          priority;       // with AUDIO_FLAG_SCHEDULE_REALTIME: 1..99
    char         stream_name[AUDIO_STREAM_NAME_MAX];   // JACK client name
    char         device_name[AUDIO_DEVICE_NAME_MAX];   // ALSA PCM name / JACK client to connect to
    static struct AudioStreamOptions none();
    static struct AudioStreamOptions with_flags(unsigned int flags);
};

int callback(&AudioIo io, ?&T user);   // AUDIO_CB_CONTINUE, AUDIO_CB_STOP or AUDIO_CB_ABORT

struct AudioIo {
    []unsigned char output_, input_;     // the buffers' bytes; empty for the direction not opened
    unsigned int frames;
    double       stream_time;            // seconds processed before this period
    unsigned int status;                 // AUDIO_STATUS_INPUT_OVERFLOW | AUDIO_STATUS_OUTPUT_UNDERFLOW
    int          output_channels, input_channels;
    unsigned int format;
    int          interleaved;
    unsigned int sample_rate;

    []float              output_f32() const;   // input_f32() is []const float; also _f64, _i16, _i32, _i8
    []S24                output_i24() const;   // packed 3-byte samples (std/audio/s24.h)
    []unsigned char      output_bytes() const; // any format
    []float              output_channel_f32(int ch) const;  // one channel of a non-interleaved f32 stream
    void clear_output() const;
};

struct AudioStream {
    ?&struct AudioStreamState_ impl;   // std-private; null when closed
    static struct AudioStream closed();

    struct AudioError start();
    struct AudioError stop();             // play out what's queued, then stop
    struct AudioError abort();            // stop now
    void close() consume;                 // abort if running; release everything; idempotent

    int    is_open() const;
    int    is_running() const;            // 0 after the callback returned STOP/ABORT, too
    int    state() const;                 // AUDIO_STREAM_CLOSED / _STOPPED / _RUNNING
    double stream_time() const;           // frames processed / sample rate
    void   set_stream_time(double seconds);
    long   latency() const;               // input + output, frames
    long   output_latency() const;
    long   input_latency() const;
    unsigned int sample_rate() const;
    unsigned int buffer_frames() const;
    int    api() const;
    struct AudioError last_error() const; // what stopped the stream from its own thread
    int    pump();                        // AUDIO_FLAG_DUMMY_MANUAL: run one period now
};

struct AudioError {
    int  code;                                 // AUDIO_OK or AUDIO_ERR_*
    char message[AUDIO_ERROR_MESSAGE_MAX];     // "alsa: snd_pcm_open: Device or resource busy"
    int ok() const;                            // AUDIO_OK or AUDIO_ERR_WARNING
    int failed() const;
    static struct AudioError none();
};
const &char audio_error_name(int code);

unsigned long audio_f32_to_i16([]const float in, []short out);   // and back: audio_i16_to_f32
unsigned long audio_f32_to_i32([]const float in, []int out);         // and back
unsigned long audio_f32_to_i24([]const float in, []S24 out);         // packed 3-byte; and back
unsigned long audio_f32_to_i8([]const float in, []signed char out);  // and back
unsigned long audio_f32_to_f64([]const float in, []double out);      // and back
unsigned long audio_i16_to_i32([]const short in, []int out);         // and back
// each converts min(in.len, out.len) samples and returns that count
unsigned long audio_f32_to_i16_dither([]const float in, []short out, &unsigned int state);  // TPDF

// frames = min(planar.len, out.len) / channels; returns it
unsigned long audio_interleave_f32([]const float planar, []float out, int channels);
unsigned long audio_deinterleave_f32([]const float in, []float planar, int channels);
void audio_gain_f32([]float buf, float gain);
unsigned long audio_mix_f32([]float dst, []const float src, float gain);
float audio_peak_f32([]const float buf);

// std/dsp interop
unsigned long audio_f32_to_fixed([]const float in, []Fixed out);   // Q8.24
unsigned long audio_fixed_to_f32([]const Fixed in, []float out);
unsigned long audio_buffer_write_f32(&AudioBuffer buf, []const float in);   // in.len / channels frames
unsigned long audio_buffer_read_f32(&AudioBuffer buf, []float out);         // up to out.len / channels

struct MidiIn {
    static struct Result<MidiIn, AudioError> open(int api, const &char client_name, unsigned long queue_bytes);
    static struct MidiIn closed();
    int  api() const;
    unsigned int port_count();
    struct Result<MidiPortInfo, AudioError> port_info(unsigned int index);   // .name
    struct AudioError open_port(unsigned int index, const &char port_name);
    struct AudioError open_virtual_port(const &char port_name);
    void close_port();
    int  is_port_open() const;

    generic<T> void set_callback(fn void(&MidiEvent, ?&T) callback, ?&T user);
    void cancel_callback();                                   // back to the queue
    void ignore_types(int sysex, int timing, int active_sensing);   // default: all three ignored
    long get_message([]unsigned char buf, &double timestamp);
    unsigned long dropped() const;
    void close() consume;
};

struct MidiOut {
    static struct Result<MidiOut, AudioError> open(int api, const &char client_name);
    // port_count, port_info, open_port, open_virtual_port, close_port, is_port_open, close as above
    struct AudioError send_message([]const unsigned char msg);   // one whole message
    struct AudioError send(struct MidiMsg msg);
};

struct MidiEvent {
    double timestamp;                  // seconds since the port opened (monotonic)
    double delta;                      // since the previous message
    []const unsigned char bytes;       // valid during the callback
    int status() const;
    struct MidiMsg short_msg() const;  // len 0 for sysex
};

struct MidiMsg {                      // up to 3 bytes: everything but sysex
    unsigned char data[3];
    int           len;
    static struct MidiMsg note_on(int channel, int note, int velocity);
    static struct MidiMsg note_off(int channel, int note, int velocity);
    static struct MidiMsg poly_pressure(int channel, int note, int pressure);
    static struct MidiMsg control_change(int channel, int controller, int value);
    static struct MidiMsg program_change(int channel, int program);
    static struct MidiMsg channel_pressure(int channel, int pressure);
    static struct MidiMsg pitch_bend(int channel, int value);       // -8192 .. 8191
    static struct MidiMsg song_position(int beats);
    static struct MidiMsg song_select(int song);
    static struct MidiMsg system(int status);                       // MIDI_CLOCK, MIDI_START, ...
    static struct MidiMsg of([]const unsigned char bytes);
    int status() const;  int type() const;  int channel() const;
    int data1() const;   int data2() const;
    int is_note_on() const;  int is_note_off() const;  int pitch_bend_value() const;
};

int  midi_message_length(int status);       // 1..3, 0 for sysex, -1 for a data byte
int  midi_is_realtime(int status);
long midi_build_sysex([]unsigned char out, []const unsigned char payload);
int  midi_14bit(int lsb, int msb);

struct MidiParser {
    static struct MidiParser new([]unsigned char sysex_buf);
    int  feed(int byte);                 // MIDI_PARSE_NONE / _MESSAGE / _SYSEX / _ERROR
    struct MidiMsg message() const;      // after MIDI_PARSE_MESSAGE
    unsigned long sysex_length() const;  // after MIDI_PARSE_SYSEX (in sysex_buf, F0 .. F7)
    void reset();
};

struct MidiEncoder {
    static struct MidiEncoder new(int use_running_status);
    long encode([]const unsigned char msg, []unsigned char out);
    void reset();
};