winzik/docker/ext/php-sdl-mixer-stream.patch
David Nurdin abe53600c5 Continuous music stream on SDL_mixer's output (no gaps between blocks)
Desktop: the music was played as one SDL_mixer chunk per block, each started
when the previous one ended, at frame precision: a gap of up to a frame at each
block (measured on the real Freedoom song: 8 gaps, 371 ms of silence in 5 s).

- php-sdl-mixer (docker/ext/php-sdl-mixer-stream.patch): a ring buffer fed by
  PHP (JumPHP_StreamOpen / Push / Buffered / Clear / Volume / Close), read by
  Mix_HookMusic on SDL's audio thread, mixed with the sound effects by SDL_mixer,
  silence when empty. Resampling to the device rate in C.
- Mix_VolumeMusic does not reach the hook: the stream volume is set by PHP.
- PcmStream (desktop): uses the stream when the binding has it, the old chunks
  otherwise. The browser path is unchanged.
- Same functions in the desktop image and in the WebAssembly engine.
- Measured in capture (SDL disk driver): 0 gaps, the right frequency, sound
  effects and music in the same output. Listening test not done yet.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-11-14 17:16:10 +01:00

363 lines
11 KiB
Diff

diff --git a/config.m4 b/config.m4
index b5c3878..3ce7bb7 100644
--- a/config.m4
+++ b/config.m4
@@ -47,6 +47,6 @@ if test "$PHP_SDL_MIXER" != "no"; then
AC_DEFINE(HAVE_SDL_MIXER, 1, [ Have sdl_mixer support ])
PHP_SUBST(SDL_MIXER_SHARED_LIBADD)
- PHP_NEW_EXTENSION(sdl_mixer, src/effect_position.c src/effect_stereoreverse.c src/Mix_Music.c src/Mix_Chunk.c src/music.c src/mixer.c php_sdl_mixer.c, $ext_shared)
+ PHP_NEW_EXTENSION(sdl_mixer, src/effect_position.c src/effect_stereoreverse.c src/Mix_Music.c src/Mix_Chunk.c src/music.c src/mixer.c src/jumphp_stream.c php_sdl_mixer.c, $ext_shared)
PHP_ADD_EXTENSION_DEP(sdl_mixer, sdl)
fi
diff --git a/php_sdl_mixer.c b/php_sdl_mixer.c
index 4d5cbd6..ac12a8d 100644
--- a/php_sdl_mixer.c
+++ b/php_sdl_mixer.c
@@ -1,6 +1,7 @@
#include "php_sdl_mixer.h"
#include "src/mixer.h"
#include "src/music.h"
+#include "src/jumphp_stream.h"
#include "php_sdl_mixer_arginfo.h"
#include "zend_smart_string.h"
diff --git a/php_sdl_mixer_arginfo.h b/php_sdl_mixer_arginfo.h
index 5af4cbc..c222e6c 100644
--- a/php_sdl_mixer_arginfo.h
+++ b/php_sdl_mixer_arginfo.h
@@ -324,6 +324,28 @@ ZEND_FUNCTION(SDL_GetError);
ZEND_FUNCTION(SDL_ClearError);
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_JumPHP_StreamOpen, 0, 2, _IS_BOOL, 0)
+ ZEND_ARG_TYPE_INFO(0, rate, IS_LONG, 0)
+ ZEND_ARG_TYPE_INFO(0, channels, IS_LONG, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_JumPHP_StreamPush, 0, 1, IS_DOUBLE, 0)
+ ZEND_ARG_TYPE_INFO(0, pcm, IS_STRING, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_JumPHP_StreamBuffered, 0, 0, IS_DOUBLE, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_JumPHP_StreamClear, 0, 0, IS_VOID, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_JumPHP_StreamVolume, 0, 1, IS_VOID, 0)
+ ZEND_ARG_TYPE_INFO(0, volume, IS_DOUBLE, 0)
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_JumPHP_StreamClose, 0, 0, IS_VOID, 0)
+ZEND_END_ARG_INFO()
+
static const zend_function_entry ext_functions[] = {
ZEND_FE(Mix_Init, arginfo_Mix_Init)
ZEND_FE(Mix_Quit, arginfo_Mix_Quit)
@@ -391,5 +413,11 @@ static const zend_function_entry ext_functions[] = {
ZEND_FALIAS(Mix_SetError, SDL_SetError, arginfo_Mix_SetError)
ZEND_FALIAS(Mix_GetError, SDL_GetError, arginfo_Mix_GetError)
ZEND_FALIAS(Mix_ClearError, SDL_ClearError, arginfo_Mix_ClearError)
+ ZEND_FE(JumPHP_StreamOpen, arginfo_JumPHP_StreamOpen)
+ ZEND_FE(JumPHP_StreamPush, arginfo_JumPHP_StreamPush)
+ ZEND_FE(JumPHP_StreamBuffered, arginfo_JumPHP_StreamBuffered)
+ ZEND_FE(JumPHP_StreamClear, arginfo_JumPHP_StreamClear)
+ ZEND_FE(JumPHP_StreamVolume, arginfo_JumPHP_StreamVolume)
+ ZEND_FE(JumPHP_StreamClose, arginfo_JumPHP_StreamClose)
ZEND_FE_END
};
diff --git a/src/jumphp_stream.c b/src/jumphp_stream.c
new file mode 100644
index 0000000..c4637af
--- /dev/null
+++ b/src/jumphp_stream.c
@@ -0,0 +1,261 @@
+/*
+ +----------------------------------------------------------------------+
+ | JumPHP: continuous music stream (see jumphp_stream.h). |
+ | The hook runs on SDL's audio thread: it only copies queued samples |
+ | under a mutex, and writes silence when there are none. |
+ +----------------------------------------------------------------------+
+*/
+
+#include "jumphp_stream.h"
+#include <SDL.h>
+#include <SDL_mixer.h>
+#include <string.h>
+
+/* seconds of device audio the ring can hold (the PHP side keeps about 0.25 s queued) */
+#define JS_CAPACITY_SECONDS 8
+
+static SDL_mutex *js_mutex = NULL;
+static Sint16 *js_ring = NULL; /* interleaved device-format samples */
+static size_t js_cap = 0; /* capacity in samples */
+static size_t js_head = 0; /* index of the next sample to play */
+static size_t js_count = 0; /* samples queued */
+static int js_out_rate = 0; /* device */
+static int js_out_channels = 0;
+static int js_in_rate = 0; /* what PHP pushes */
+static int js_in_channels = 0;
+static double js_pos = 0.0; /* resampling position, relative to the previous input frame */
+static Sint16 js_prev[2]; /* the last input frame (left, right) */
+static int js_has_prev = 0;
+static float js_volume = 1.0f;
+static int js_hooked = 0;
+
+/* SDL's audio thread: the next samples of the stream, silence when none are queued */
+static void js_hook(void *udata, Uint8 *stream, int len)
+{
+ Sint16 *out = (Sint16 *) stream;
+ int samples = len / 2;
+ int i = 0;
+ (void) udata;
+ if (js_mutex == NULL) {
+ memset(stream, 0, len);
+ return;
+ }
+ SDL_LockMutex(js_mutex);
+ while (i < samples && js_count > 0) {
+ double v = js_ring[js_head] * (double) js_volume;
+ if (v > 32767.0) v = 32767.0;
+ if (v < -32768.0) v = -32768.0;
+ out[i++] = (Sint16) v;
+ js_head = (js_head + 1) % js_cap;
+ js_count--;
+ }
+ SDL_UnlockMutex(js_mutex);
+ for (; i < samples; i++) {
+ out[i] = 0;
+ }
+}
+
+/* one device frame into the ring (the lock is held); the oldest sample goes when it is full */
+static void js_emit(Sint16 left, Sint16 right)
+{
+ Sint16 frame[2];
+ int c;
+ if (js_out_channels == 1) {
+ frame[0] = (Sint16) (((int) left + (int) right) / 2);
+ } else {
+ frame[0] = left;
+ frame[1] = right;
+ }
+ for (c = 0; c < js_out_channels; c++) {
+ if (js_count >= js_cap) {
+ js_head = (js_head + 1) % js_cap;
+ js_count--;
+ }
+ js_ring[(js_head + js_count) % js_cap] = frame[c];
+ js_count++;
+ }
+}
+
+static double js_buffered_seconds(void)
+{
+ if (js_out_rate <= 0 || js_out_channels <= 0) {
+ return 0.0;
+ }
+ return (double) js_count / ((double) js_out_rate * js_out_channels);
+}
+
+/* {{{ JumPHP_StreamOpen(int $rate, int $channels): bool
+ The format PHP pushes (signed 16-bit little-endian, mono or stereo). Needs an open Mix_OpenAudio. */
+PHP_FUNCTION(JumPHP_StreamOpen)
+{
+ zend_long rate, channels;
+ int freq = 0, device_channels = 0;
+ Uint16 format = 0;
+ ZEND_PARSE_PARAMETERS_START(2, 2)
+ Z_PARAM_LONG(rate)
+ Z_PARAM_LONG(channels)
+ ZEND_PARSE_PARAMETERS_END();
+
+ if (rate <= 0 || (channels != 1 && channels != 2)) {
+ RETURN_FALSE;
+ }
+ if (!Mix_QuerySpec(&freq, &format, &device_channels) || format != AUDIO_S16SYS || freq <= 0) {
+ RETURN_FALSE; /* the mixer is not open, or not 16-bit: nothing to play into */
+ }
+ if (js_mutex == NULL) {
+ js_mutex = SDL_CreateMutex();
+ if (js_mutex == NULL) {
+ RETURN_FALSE;
+ }
+ }
+ SDL_LockMutex(js_mutex);
+ free(js_ring);
+ js_cap = (size_t) freq * device_channels * JS_CAPACITY_SECONDS;
+ js_ring = (Sint16 *) calloc(js_cap, sizeof(Sint16));
+ js_head = 0;
+ js_count = 0;
+ js_out_rate = freq;
+ js_out_channels = device_channels;
+ js_in_rate = (int) rate;
+ js_in_channels = (int) channels;
+ js_pos = 0.0;
+ js_has_prev = 0;
+ SDL_UnlockMutex(js_mutex);
+ if (js_ring == NULL) {
+ RETURN_FALSE;
+ }
+ if (!js_hooked) {
+ Mix_HookMusic(js_hook, NULL);
+ js_hooked = 1;
+ }
+ RETURN_TRUE;
+}
+/* }}} */
+
+/* {{{ JumPHP_StreamPush(string $pcm): float
+ Appends samples (in the format of JumPHP_StreamOpen), resampled to the device. Returns the seconds queued. */
+PHP_FUNCTION(JumPHP_StreamPush)
+{
+ zend_string *pcm;
+ ZEND_PARSE_PARAMETERS_START(1, 1)
+ Z_PARAM_STR(pcm)
+ ZEND_PARSE_PARAMETERS_END();
+
+ if (js_mutex == NULL || js_ring == NULL || js_out_rate <= 0 || js_in_rate <= 0) {
+ RETURN_DOUBLE(0.0);
+ }
+ {
+ const unsigned char *data = (const unsigned char *) ZSTR_VAL(pcm);
+ size_t frames = ZSTR_LEN(pcm) / (2 * (size_t) js_in_channels);
+ size_t n = frames + 1, k;
+ Sint16 *a = (Sint16 *) malloc(n * 2 * sizeof(Sint16));
+ double step = (double) js_in_rate / (double) js_out_rate;
+ double buffered;
+ if (a == NULL) {
+ RETURN_DOUBLE(0.0);
+ }
+ /* index 0: the previous input frame (or the first one, at the start), then the new frames */
+ a[0] = js_has_prev ? js_prev[0] : 0;
+ a[1] = js_has_prev ? js_prev[1] : 0;
+ for (k = 0; k < frames; k++) {
+ Sint16 left, right;
+ const unsigned char *p = data + k * 2 * js_in_channels;
+ left = (Sint16) (p[0] | (p[1] << 8));
+ if (js_in_channels == 2) {
+ right = (Sint16) (p[2] | (p[3] << 8));
+ } else {
+ right = left;
+ }
+ a[2 * (k + 1)] = left;
+ a[2 * (k + 1) + 1] = right;
+ }
+ if (!js_has_prev && frames > 0) {
+ a[0] = a[2];
+ a[1] = a[3];
+ }
+ SDL_LockMutex(js_mutex);
+ while (js_pos + 1.0 < (double) n) {
+ size_t i = (size_t) js_pos;
+ double f = js_pos - (double) i;
+ double left = a[2 * i] * (1.0 - f) + a[2 * (i + 1)] * f;
+ double right = a[2 * i + 1] * (1.0 - f) + a[2 * (i + 1) + 1] * f;
+ js_emit((Sint16) left, (Sint16) right);
+ js_pos += step;
+ }
+ js_pos -= (double) (n - 1);
+ if (n > 1) {
+ js_prev[0] = a[2 * (n - 1)];
+ js_prev[1] = a[2 * (n - 1) + 1];
+ js_has_prev = 1;
+ }
+ buffered = js_buffered_seconds();
+ SDL_UnlockMutex(js_mutex);
+ free(a);
+ RETURN_DOUBLE(buffered);
+ }
+}
+/* }}} */
+
+/* {{{ JumPHP_StreamBuffered(): float -- seconds queued and not played yet */
+PHP_FUNCTION(JumPHP_StreamBuffered)
+{
+ double buffered = 0.0;
+ ZEND_PARSE_PARAMETERS_START(0, 0)
+ ZEND_PARSE_PARAMETERS_END();
+ if (js_mutex != NULL) {
+ SDL_LockMutex(js_mutex);
+ buffered = js_buffered_seconds();
+ SDL_UnlockMutex(js_mutex);
+ }
+ RETURN_DOUBLE(buffered);
+}
+/* }}} */
+
+/* {{{ JumPHP_StreamClear(): void -- drops what is queued (a new tune) */
+PHP_FUNCTION(JumPHP_StreamClear)
+{
+ ZEND_PARSE_PARAMETERS_START(0, 0)
+ ZEND_PARSE_PARAMETERS_END();
+ if (js_mutex != NULL) {
+ SDL_LockMutex(js_mutex);
+ js_head = 0;
+ js_count = 0;
+ js_pos = 0.0;
+ js_has_prev = 0;
+ SDL_UnlockMutex(js_mutex);
+ }
+}
+/* }}} */
+
+/* {{{ JumPHP_StreamVolume(float $volume): void -- 0..1, applied on the stream only */
+PHP_FUNCTION(JumPHP_StreamVolume)
+{
+ double volume;
+ ZEND_PARSE_PARAMETERS_START(1, 1)
+ Z_PARAM_DOUBLE(volume)
+ ZEND_PARSE_PARAMETERS_END();
+ if (volume < 0.0) volume = 0.0;
+ if (volume > 1.0) volume = 1.0;
+ if (js_mutex != NULL) {
+ SDL_LockMutex(js_mutex);
+ js_volume = (float) volume;
+ SDL_UnlockMutex(js_mutex);
+ }
+}
+/* }}} */
+
+/* {{{ JumPHP_StreamClose(): void */
+PHP_FUNCTION(JumPHP_StreamClose)
+{
+ ZEND_PARSE_PARAMETERS_START(0, 0)
+ ZEND_PARSE_PARAMETERS_END();
+ if (js_mutex != NULL) {
+ SDL_LockMutex(js_mutex);
+ free(js_ring);
+ js_ring = NULL;
+ js_cap = js_count = js_head = 0;
+ js_out_rate = js_out_channels = js_in_rate = js_in_channels = 0;
+ SDL_UnlockMutex(js_mutex);
+ }
+}
+/* }}} */
diff --git a/src/jumphp_stream.h b/src/jumphp_stream.h
new file mode 100644
index 0000000..206d66c
--- /dev/null
+++ b/src/jumphp_stream.h
@@ -0,0 +1,21 @@
+/*
+ +----------------------------------------------------------------------+
+ | JumPHP: a continuous music stream on SDL_mixer's own output (the |
+ | device is shared with the sound effects). PHP pushes raw PCM; SDL |
+ | mixes it with the chunks, in order, without gaps. Silence when empty.|
+ +----------------------------------------------------------------------+
+*/
+
+#ifndef JUMPHP_STREAM_H
+#define JUMPHP_STREAM_H
+
+#include "php.h"
+
+PHP_FUNCTION(JumPHP_StreamOpen);
+PHP_FUNCTION(JumPHP_StreamPush);
+PHP_FUNCTION(JumPHP_StreamBuffered);
+PHP_FUNCTION(JumPHP_StreamClear);
+PHP_FUNCTION(JumPHP_StreamVolume);
+PHP_FUNCTION(JumPHP_StreamClose);
+
+#endif