commit 170ee1e7a887017d477409c80bace4ecc2aacef7
parent 138518b298f29d4d587f2e8494c802e06d81af92
Author: Eamon Caddigan <eamon.caddigan@gmail.com>
Date: Mon, 18 Dec 2023 20:28:26 -0800
Starting notes on audio handling
Diffstat:
| A | audio_notes.md | | | 58 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 58 insertions(+), 0 deletions(-)
diff --git a/audio_notes.md b/audio_notes.md
@@ -0,0 +1,58 @@
+# How does Audio work in uxn's reference implementation?
+
+This is just a collection of notes, I'm not trying to form a coherent
+narrative here!
+
+## The code
+
+Most of the implementation lives in
+[audio.c](https://git.sr.ht/~rabbits/uxn/tree/main/item/src/devices/audio.c).
+The notable exception is `audio_deo` in
+[uxnemu.c](https://git.sr.ht/~rabbits/uxn/tree/main/item/src/uxnemu.c). This
+last function is where uxn calls SDL's audio handling, which triggers when a
+value is written to the `pitch` port (see below). `audio_finished_handler`
+is also defined in `uxnemu.c`. This provides nice separation between generic
+audio stuff and SDL functions, although `audio_handler` is an
+[SDL_AudioSpec](https://wiki.libsdl.org/SDL2/SDL_AudioSpec) callback.
+
+Many (maybe "most", but I'm not counting) of the functions are `void` type
+and modify their arguments.
+
+The header file
+[audio.h](https://git.sr.ht/~rabbits/uxn/tree/main/item/src/devices/audio.h)
+has a signature for an `audio_render` that I can't find defined anywhere.
+
+Only `audio_dei`, `audio_handler`, and `audio_start` are defined in
+`audio.c` and referenced elsewhere in the code (all in `uxnemu.c`).
+
+## The ports
+
+ |30 @Audio0 [ &vector $2 &position $2 &output $1 &duration $2 &pad $1 &adsr $2 &length $2 &addr $2 &volume $1 &pitch $1 ]
+
+`duration` was added in the October refactor, and `asdr` works differently
+than it used to.
+
+## Pitch
+
+The low seven bits of the pitch byte corresponds to a [midi
+note](https://wiki.xxiivv.com/site/midi.html) (microtonality is supposedly
+possible if I'm reading the Git logs correctly, but I'm not sure how that's
+implemented yet).
+
+Sending a pitch of `0x00` appears to stop playback.
+
+The lowest supported note is `0x20`,
+
+The highest bit of the pitch byte (still) controls looping behavior (so the highest pitch supported is `0x7f`, an 8-octave range.
+
+Notes are converted to frequencies by the `tuning` lookup table. This table
+is 109 elements long even though there are only 96 possible notes?
+
+The elements in the tuning table represent each note's frequency (in Hz)
+divided by 44104.31 (95% CI: 44104.30-44104.32), approximately the value of
+the `SAMPLE_FREQUENCY` (44100.0 Hz) defined in
+[audio.h](https://git.sr.ht/~rabbits/uxn/tree/main/item/src/devices/audio.h).
+I.e., this value gives the (fractional) number of cycles of the waveform per
+audio sample for a given note.
+
+## To Be Continued
