xbintsc 0.5.32 → 0.5.37

package/runtime/ext_gui/audio_buffer.cpp

@@ -0,0 +1,166 @@
+/*
+ * xbintsc GUI engine — AudioBuffer value construction and sample transfer.
+ *
+ * The mixer never sees an `xt_value`: `audio_clip_from_buffer` copies the
+ * samples a BufferSource needs when it starts, so a later collection of the
+ * AudioBuffer (or a mutation of its Float32Arrays) cannot race the audio
+ * thread. `audio_buffer_create` fills a freshly decoded buffer through the
+ * runtime's bulk ArrayBuffer copy instead of one JS property write per sample.
+ */
+
+#include "audio_buffer.h"
+
+#include <cstring>
+
+#include "audio_mixer.h"
+
+namespace xtgui {
+
+namespace {
+
+/* Byte endianness matches the host, which is what the runtime's typed array
+ * read/write also assumes (it memcpy's the element bytes). */
+xt_value make_channel(const float *samples, uint32_t length) {
+  xt_value array_buffer = xt_array_buffer_alloc(length * static_cast<uint32_t>(sizeof(float)));
+  if (samples != nullptr && length > 0) {
+    xt_array_buffer_copy_bytes_in(array_buffer, 0,
+                                  reinterpret_cast<const uint8_t *>(samples),
+                                  length * static_cast<uint32_t>(sizeof(float)));
+  }
+  xt_value constructor_arg = array_buffer;
+  return xt_typed_array_ctor_by_name(xt_string_from_cstr("Float32Array"), 1, &constructor_arg);
+}
+
+xt_value buffer_get_channel_data(xt_value self, xt_value env, int32_t argc, xt_value *argv);
+
+xt_value empty_channel() {
+  xt_value zero = xt_number(0);
+  return xt_typed_array_ctor_by_name(xt_string_from_cstr("Float32Array"), 1, &zero);
+}
+
+/** A channel's bytes: the typed array's backing buffer plus its view range. */
+bool channel_bytes(xt_value channel, std::vector<uint8_t> *out, uint32_t *length) {
+  if (!xt_is_typed_array(channel)) return false;
+  xt_value buffer = xt_typed_array_backing_buffer(channel);
+  uint32_t offset = xt_typed_array_view_offset(channel);
+  uint32_t byte_length =
+      static_cast<uint32_t>(xt_to_number(xt_object_get_cstr(channel, "byteLength")));
+  if (!XT_IS_OBJECT(buffer) || byte_length < sizeof(float)) return false;
+  out->resize(byte_length);
+  if (xt_array_buffer_copy_bytes_out(buffer, offset, out->data(), byte_length) != byte_length) {
+    return false;
+  }
+  *length = byte_length / static_cast<uint32_t>(sizeof(float));
+  return true;
+}
+
+}  // namespace
+
+xt_value audio_buffer_create(const std::vector<std::vector<float>> &channels, int sample_rate) {
+  uint32_t length = channels.empty() ? 0 : static_cast<uint32_t>(channels[0].size());
+  xt_value channel_array = xt_array_new(0, nullptr);
+  for (const std::vector<float> &channel : channels) {
+    xt_array_push(channel_array, make_channel(channel.data(),
+                                              static_cast<uint32_t>(channel.size())));
+  }
+  xt_value buffer = xt_object_new();
+  xt_object_set(buffer, xt_string_from_cstr("__xt_audio_channels"), channel_array);
+  xt_object_set(buffer, xt_string_from_cstr("getChannelData"),
+                xt_closure_new(reinterpret_cast<void *>(buffer_get_channel_data), 0, nullptr));
+  xt_object_set(buffer, xt_string_from_cstr("numberOfChannels"),
+                xt_number(static_cast<double>(channels.size())));
+  xt_object_set(buffer, xt_string_from_cstr("length"), xt_number(static_cast<double>(length)));
+  xt_object_set(buffer, xt_string_from_cstr("sampleRate"),
+                xt_number(static_cast<double>(sample_rate)));
+  xt_object_set(buffer, xt_string_from_cstr("duration"),
+                xt_number(sample_rate > 0 ? static_cast<double>(length) / sample_rate : 0.0));
+  xt_object_set(buffer, xt_string_from_cstr("__xt_audio_ready"), XT_TRUE);
+  return buffer;
+}
+
+std::shared_ptr<AudioClip> audio_clip_from_buffer(xt_value buffer) {
+  xt_value channels = xt_object_get_cstr(buffer, "__xt_audio_channels");
+  if (!XT_IS_ARRAY(channels) && !XT_IS_OBJECT(channels)) return nullptr;
+  int count = xt_array_size(channels);
+  if (count <= 0) return nullptr;
+  if (count > 2) count = 2; /* the mixer is stereo; extra channels are dropped */
+  auto clip = std::make_shared<AudioClip>();
+  clip->sample_rate =
+      static_cast<int>(xt_to_number(xt_object_get_cstr(buffer, "sampleRate")));
+  if (clip->sample_rate <= 0) clip->sample_rate = kAudioMixRate;
+  for (int index = 0; index < count; index++) {
+    xt_value channel = xt_array_get(channels, xt_number(static_cast<double>(index)));
+    std::vector<uint8_t> bytes;
+    uint32_t length = 0;
+    if (!channel_bytes(channel, &bytes, &length)) return nullptr;
+    std::vector<float> samples(length);
+    if (length > 0) std::memcpy(samples.data(), bytes.data(), bytes.size());
+    if (index == 0) {
+      clip->length = length;
+    } else if (length != clip->length) {
+      /* Keep every channel the same length; the mixer indexes all of them with
+       * the first channel's length. */
+      if (length < clip->length) clip->length = length;
+      for (std::vector<float> &existing : clip->channels) existing.resize(clip->length);
+      samples.resize(clip->length);
+    }
+    clip->channels.push_back(std::move(samples));
+  }
+  if (clip->length == 0) return nullptr;
+  return clip;
+}
+
+bool audio_bytes_from_value(xt_value value, std::vector<uint8_t> *out) {
+  /* `fs.readFileSync` returns a byte string in this runtime (there is no
+   * dedicated binary value type). Its storage is the file's raw bytes, so a
+   * decoded audio file can be handed over directly. */
+  if (XT_IS_STRING(value)) {
+    int32_t bytes = xt_string_length_value(value);
+    const char *data = xt_string_data(value);
+    if (data == nullptr || bytes <= 0) return false;
+    out->assign(data, data + bytes);
+    return true;
+  }
+  xt_value buffer = value;
+  uint32_t offset = 0;
+  uint32_t length = 0;
+  if (xt_is_typed_array(value)) {
+    /* A typed array view: decode only the view's bytes. */
+    buffer = xt_typed_array_backing_buffer(value);
+    offset = xt_typed_array_view_offset(value);
+    length = static_cast<uint32_t>(xt_to_number(xt_object_get_cstr(value, "byteLength")));
+  } else {
+    length = static_cast<uint32_t>(xt_to_number(xt_object_get_cstr(value, "byteLength")));
+  }
+  if (XT_IS_OBJECT(buffer) && length > 0) {
+    out->resize(length);
+    return xt_array_buffer_copy_bytes_out(buffer, offset, out->data(), length) == length;
+  }
+  /* A Node `Buffer` is a plain object with numeric elements and a `length`
+   * (xbintsc has no dedicated binary value type). Node programs routinely pass
+   * `readFileSync(...)` straight to `decodeAudioData`, so accept that shape. */
+  xt_value count = xt_object_get_cstr(value, "length");
+  if (!XT_IS_OBJECT(value) || !XT_IS_NUMBER(count) || xt_to_number(count) <= 0) return false;
+  uint32_t bytes = static_cast<uint32_t>(xt_to_number(count));
+  out->resize(bytes);
+  for (uint32_t index = 0; index < bytes; index++) {
+    (*out)[index] = static_cast<uint8_t>(
+        xt_to_number(xt_object_get(value, xt_number(static_cast<double>(index)))));
+  }
+  return true;
+}
+
+namespace {
+
+xt_value buffer_get_channel_data(xt_value self, xt_value env, int32_t argc, xt_value *argv) {
+  (void)env;
+  xt_value channels = xt_object_get_cstr(self, "__xt_audio_channels");
+  int index = static_cast<int>(xt_to_number(xt_arg(argc, argv, 0)));
+  if (!XT_IS_ARRAY(channels) && !XT_IS_OBJECT(channels)) return empty_channel();
+  if (index < 0 || index >= xt_array_size(channels)) return empty_channel();
+  return xt_array_get(channels, xt_number(static_cast<double>(index)));
+}
+
+}  // namespace
+
+}  // namespace xtgui

package/runtime/ext_gui/audio_buffer.h

@@ -0,0 +1,37 @@
+/*
+ * xbintsc GUI engine — the AudioBuffer bridge.
+ *
+ * An AudioBuffer is a JavaScript object whose channels are real
+ * `Float32Array`s, so a page can read and write samples with the normal typed
+ * array API. These helpers convert between that representation and the native
+ * `AudioClip` the mixer reads, and between an ArrayBuffer/typed-array argument
+ * and the bytes a decoder consumes.
+ */
+#ifndef XT_GUI_AUDIO_BUFFER_H
+#define XT_GUI_AUDIO_BUFFER_H
+
+#include <cstdint>
+#include <memory>
+#include <vector>
+
+#include "rt.h"
+
+namespace xtgui {
+
+struct AudioClip;
+
+/** Build an AudioBuffer value from planar float channels. The channel count and
+ * length come from the vectors; `sample_rate` is the buffer's own rate. */
+xt_value audio_buffer_create(const std::vector<std::vector<float>> &channels, int sample_rate);
+
+/** Copy an AudioBuffer value's channels into a mixer clip. Returns null when the
+ * value is not an AudioBuffer or has no samples. */
+std::shared_ptr<AudioClip> audio_clip_from_buffer(xt_value buffer);
+
+/** Read the bytes behind an ArrayBuffer or a typed array view (for
+ * `decodeAudioData`). */
+bool audio_bytes_from_value(xt_value value, std::vector<uint8_t> *out);
+
+}  // namespace xtgui
+
+#endif /* XT_GUI_AUDIO_BUFFER_H */

package/runtime/ext_gui/audio_decode.cpp

@@ -0,0 +1,219 @@
+/*
+ * xbintsc GUI engine — Web Audio byte decoding.
+ *
+ * `AudioContext.decodeAudioData` accepts an ArrayBuffer. WAV (PCM, IEEE float,
+ * A-law and µ-law) is decoded here with no dependency, which keeps the common
+ * "generate a WAV in TypeScript / play a .wav file" case working with `gui`
+ * alone. Every other container and codec is delegated to the optional `media`
+ * extension, whose FFmpeg build already carries MP3, AAC, Vorbis, Opus and
+ * FLAC (see `xt_media_decode_audio` in `media.h`).
+ *
+ * The output is interleaved, which is what the FFmpeg bridge naturally
+ * produces; `audio.cpp` deinterleaves it into the AudioBuffer's channels and
+ * the mixer's planar clip.
+ */
+
+#include "audio_decode.h"
+
+#include <cmath>
+#include <cstring>
+
+#include "media.h"
+
+namespace xtgui {
+
+namespace {
+
+uint16_t read_u16(const uint8_t *data) {
+  return static_cast<uint16_t>(data[0] | (data[1] << 8));
+}
+
+uint32_t read_u32(const uint8_t *data) {
+  return static_cast<uint32_t>(data[0]) | (static_cast<uint32_t>(data[1]) << 8) |
+         (static_cast<uint32_t>(data[2]) << 16) | (static_cast<uint32_t>(data[3]) << 24);
+}
+
+bool fail(std::string *error, const char *message) {
+  if (error != nullptr) *error = message;
+  return false;
+}
+
+/** G.711 A-law, as stored in a WAV `ALAW` stream: after the 0x55 XOR the sign
+ * bit (0x80) is set for positive samples. */
+double decode_alaw(uint8_t value) {
+  value ^= 0x55;
+  int sign = value & 0x80 ? 1 : -1;
+  int exponent = (value >> 4) & 0x07;
+  int mantissa = value & 0x0f;
+  int magnitude = exponent == 0 ? (mantissa << 4) + 8
+                                : ((mantissa << 4) + 0x108) << (exponent - 1);
+  return sign * magnitude / 32768.0;
+}
+
+/** G.711 µ-law; the WAV variant is the complement of the raw bit stream. */
+double decode_mulaw(uint8_t value) {
+  value = static_cast<uint8_t>(~value);
+  int sign = value & 0x80 ? -1 : 1;
+  int exponent = (value >> 4) & 0x07;
+  int mantissa = value & 0x0f;
+  int magnitude = (((mantissa << 3) + 0x84) << exponent) - 0x84;
+  return sign * magnitude / 32768.0;
+}
+
+struct WavFormat {
+  uint16_t tag = 0;
+  uint16_t channels = 0;
+  uint32_t sample_rate = 0;
+  uint16_t block_align = 0;
+  uint16_t bits = 0;
+  uint32_t data_offset = 0;
+  uint32_t data_size = 0;
+};
+
+bool parse_wav(const uint8_t *data, size_t size, WavFormat *format, std::string *error) {
+  if (size < 12 || std::memcmp(data, "RIFF", 4) != 0 || std::memcmp(data + 8, "WAVE", 4) != 0) {
+    return fail(error, "not a WAV file");
+  }
+  size_t pos = 12;
+  bool have_format = false;
+  bool have_data = false;
+  while (pos + 8 <= size) {
+    const uint8_t *header = data + pos;
+    uint32_t chunk = read_u32(header + 4);
+    size_t body = pos + 8;
+    if (body > size) break;
+    if (std::memcmp(header, "fmt ", 4) == 0) {
+      if (chunk < 16 || body + 16 > size) return fail(error, "truncated WAV format chunk");
+      format->tag = read_u16(data + body);
+      format->channels = read_u16(data + body + 2);
+      format->sample_rate = read_u32(data + body + 4);
+      format->block_align = read_u16(data + body + 12);
+      format->bits = read_u16(data + body + 14);
+      /* WAVE_FORMAT_EXTENSIBLE: the real codec is the first two bytes of the
+       * SubFormat GUID, after cbSize/validBits/channelMask. */
+      if (format->tag == 0xfffe && chunk >= 40 && body + 26 <= size) {
+        format->tag = read_u16(data + body + 24);
+      }
+      have_format = true;
+    } else if (std::memcmp(header, "data", 4) == 0) {
+      if (body > size) break;
+      format->data_offset = static_cast<uint32_t>(body);
+      uint64_t available = size - body;
+      format->data_size = static_cast<uint32_t>(chunk < available ? chunk : available);
+      have_data = true;
+      break;
+    }
+    pos = body + chunk + (chunk & 1u);
+  }
+  if (!have_format) return fail(error, "WAV file has no format chunk");
+  if (!have_data) return fail(error, "WAV file has no data chunk");
+  if (format->channels == 0 || format->channels > 32) return fail(error, "invalid WAV channel count");
+  if (format->sample_rate < 8000 || format->sample_rate > 192000) {
+    return fail(error, "invalid WAV sample rate");
+  }
+  bool supported = false;
+  switch (format->tag) {
+    case 1: /* PCM */
+      supported = format->bits == 8 || format->bits == 16 || format->bits == 24 ||
+                  format->bits == 32;
+      break;
+    case 3: /* IEEE float */
+      supported = format->bits == 32 || format->bits == 64;
+      break;
+    case 6: /* A-law */
+    case 7: /* µ-law */
+      supported = format->bits == 8;
+      break;
+    default:
+      break;
+  }
+  if (!supported) return fail(error, "unsupported WAV codec");
+  return true;
+}
+
+double pcm_sample(const uint8_t *data, uint16_t bits) {
+  switch (bits) {
+    case 8:
+      return (static_cast<int>(data[0]) - 128) / 128.0;
+    case 16:
+      return static_cast<int16_t>(data[0] | (data[1] << 8)) / 32768.0;
+    case 24: {
+      int32_t value = data[0] | (data[1] << 8) | (data[2] << 16);
+      if (value & 0x800000) value |= ~0xffffff;
+      return value / 8388608.0;
+    }
+    case 32: {
+      int32_t value = static_cast<int32_t>(read_u32(data));
+      return value / 2147483648.0;
+    }
+    default:
+      return 0.0;
+  }
+}
+
+bool decode_wav(const uint8_t *data, size_t size, DecodedAudio *out, std::string *error) {
+  WavFormat format;
+  if (!parse_wav(data, size, &format, error)) return false;
+  uint32_t frame_bytes;
+  switch (format.tag) {
+    case 1:
+      frame_bytes = format.channels * (format.bits / 8u);
+      break;
+    case 3:
+      frame_bytes = format.channels * (format.bits / 8u);
+      break;
+    default:
+      frame_bytes = format.channels;
+      break;
+  }
+  if (format.block_align > frame_bytes) frame_bytes = format.block_align;
+  if (frame_bytes == 0) return fail(error, "invalid WAV frame size");
+  uint32_t frames = format.data_size / frame_bytes;
+  if (frames == 0) return fail(error, "WAV file has no samples");
+
+  out->sample_rate = static_cast<int>(format.sample_rate);
+  out->channels = format.channels;
+  out->frames = frames;
+  out->interleaved.assign(static_cast<size_t>(frames) * format.channels, 0.0f);
+  for (uint32_t frame = 0; frame < frames; frame++) {
+    const uint8_t *source = data + format.data_offset + static_cast<size_t>(frame) * frame_bytes;
+    for (uint16_t channel = 0; channel < format.channels; channel++) {
+      const uint8_t *sample = source + channel * (format.bits / 8u);
+      double value;
+      if (format.tag == 3) {
+        if (format.bits == 32) {
+          float narrowed;
+          std::memcpy(&narrowed, sample, sizeof(narrowed));
+          value = narrowed;
+        } else {
+          double wide;
+          std::memcpy(&wide, sample, sizeof(wide));
+          value = wide;
+        }
+      } else if (format.tag == 6) {
+        value = decode_alaw(sample[0]);
+      } else if (format.tag == 7) {
+        value = decode_mulaw(sample[0]);
+      } else {
+        value = pcm_sample(sample, format.bits);
+      }
+      out->interleaved[static_cast<size_t>(frame) * format.channels + channel] =
+          static_cast<float>(value);
+    }
+  }
+  return true;
+}
+
+}  // namespace
+
+bool decode_audio_bytes(const uint8_t *data, size_t size, DecodedAudio *out, std::string *error) {
+  if (data == nullptr || size == 0) return fail(error, "empty audio data");
+  std::string wav_error;
+  if (decode_wav(data, size, out, &wav_error)) return true;
+  std::string media_error;
+  if (xt_media_decode_audio(data, size, out, &media_error)) return true;
+  if (error != nullptr) *error = media_error.empty() ? wav_error : media_error;
+  return false;
+}
+
+}  // namespace xtgui

package/runtime/ext_gui/audio_decode.h

@@ -0,0 +1,39 @@
+/*
+ * xbintsc GUI engine — Web Audio byte decoding.
+ *
+ * `decodeAudioBytes` is what `AudioContext.decodeAudioData` calls. WAV is
+ * decoded by the engine itself; every other container/codec is delegated to
+ * the optional `media` extension, so `gui` alone still has a working decoder
+ * for the format a page usually generates.
+ */
+#ifndef XT_GUI_AUDIO_DECODE_H
+#define XT_GUI_AUDIO_DECODE_H
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace xtgui {
+
+/** Decoded PCM, interleaved, `frames * channels` floats. */
+struct DecodedAudio {
+  int channels = 0;
+  int sample_rate = 0;
+  uint32_t frames = 0;
+  std::vector<float> interleaved;
+};
+
+/**
+ * Decode `size` bytes of `data`.
+ *
+ * WAV is handled in-engine (PCM 8/16/24/32, IEEE float 32/64, A-law, µ-law).
+ * Anything else asks the `media` extension's FFmpeg decoder; without that
+ * extension the call fails with an actionable message. Returns false and fills
+ * `*error` on failure. `data` is not retained.
+ */
+bool decode_audio_bytes(const uint8_t *data, size_t size, DecodedAudio *out, std::string *error);
+
+}  // namespace xtgui
+
+#endif /* XT_GUI_AUDIO_DECODE_H */

package/runtime/ext_gui/audio_device.cpp

@@ -0,0 +1,87 @@
+/*
+ * xbintsc GUI engine — the SDL playback device behind an AudioContext.
+ *
+ * The mixer renders on demand (`AudioMixer::render`); this unit is the only
+ * place that opens a device and pumps it. SDL calls `stream_callback` on its
+ * audio thread, which renders the requested amount into the stream. A headless
+ * host simply has no device: `start_device` fails once and playback stays
+ * silent, while the graph and its clock remain usable (the offline render hook
+ * exercises the same code path).
+ */
+
+#include "audio_mixer.h"
+
+#include <SDL3/SDL.h>
+
+#include <vector>
+
+namespace xtgui {
+
+namespace {
+
+void SDLCALL stream_callback(void *userdata, SDL_AudioStream *stream, int additional_amount,
+                             int total_amount) {
+  (void)total_amount;
+  if (additional_amount <= 0) return;
+  int frames = additional_amount / static_cast<int>(sizeof(float) * kAudioMixChannels);
+  if (frames <= 0) return;
+  std::vector<float> buffer(static_cast<size_t>(frames) * kAudioMixChannels);
+  static_cast<AudioMixer *>(userdata)->render(buffer.data(), frames);
+  SDL_PutAudioStreamData(stream, buffer.data(), static_cast<int>(buffer.size() * sizeof(float)));
+}
+
+}  // namespace
+
+bool AudioMixer::start_device() {
+  if (offline_) return false;
+  std::lock_guard<std::mutex> lock(mutex_);
+  if (!running_) return false;
+  if (stream_ != nullptr) return true;
+  if (device_tried_) return false;
+  device_tried_ = true;
+  if (!SDL_InitSubSystem(SDL_INIT_AUDIO)) return false;
+  SDL_AudioSpec spec;
+  spec.format = SDL_AUDIO_F32;
+  spec.channels = kAudioMixChannels;
+  spec.freq = kAudioMixRate;
+  stream_ = SDL_OpenAudioDeviceStream(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &spec, stream_callback,
+                                      this);
+  if (stream_ == nullptr) return false;
+  SDL_ResumeAudioStreamDevice(stream_);
+  return true;
+}
+
+void AudioMixer::suspend_device() {
+  std::lock_guard<std::mutex> lock(mutex_);
+  running_ = false;
+  if (stream_ != nullptr) SDL_PauseAudioStreamDevice(stream_);
+}
+
+void AudioMixer::resume_device() {
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    running_ = true;
+  }
+  if (start_device()) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (stream_ != nullptr) SDL_ResumeAudioStreamDevice(stream_);
+  }
+}
+
+void AudioMixer::close_device() {
+  SDL_AudioStream *stream = nullptr;
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    stream = stream_;
+    stream_ = nullptr;
+    running_ = false;
+  }
+  if (stream != nullptr) SDL_DestroyAudioStream(stream);
+}
+
+bool AudioMixer::has_device() {
+  std::lock_guard<std::mutex> lock(mutex_);
+  return stream_ != nullptr;
+}
+
+}  // namespace xtgui