A cross platform Audiobookshelf client for Android and iOS
Dart
Make the loudness slider level quiet books automatically instead of adding fixed gain
Barnabas676ee21b5c76
diff --git a/ios/Runner/Audio/AudioEQProcessor.m b/ios/Runner/Audio/AudioEQProcessor.mindex b3225b0b..eb17d409 100644--- a/ios/Runner/Audio/AudioEQProcessor.m+++ b/ios/Runner/Audio/AudioEQProcessor.m@@ -28,11 +28,35 @@ typedef struct {_Atomic(int) coeffVersion;} EQParams;+// The loudness slider as an automatic level, the way a car radio's auto+// volume works. Quiet narration is pulled up toward a target peak and loud+// narration is left alone, so every book comes out at about the same level;+// the slider caps how much gain may be added, and at zero nothing is added.+// The level is followed on speech only: a short-term peak more than 30 dB+// under the recent level is a pause, and the gain holds through it instead+// of creeping up and bursting on the next sentence. Gain drops within 10 ms+// when a louder passage arrives and climbs at 8 dB a second when a quieter+// one does. Same algorithm as the Android Leveler in just_audio.+typedef struct {+ float fastCoef;+ double followCoef;+ float dropCoef;+ float riseStep;+ float fast;+ double envelope;+ float gain;+} Leveler;++static const float kLevelerTarget = 0.708f;+static const float kLevelerPauseRatio = 0.0316f;+static const float kLevelerFloor = 0.001f;+typedef struct {BiquadDelay delays[EQ_NUM_BANDS][MAX_CHANNELS];BiquadDelay bassDelay[MAX_CHANNELS];BiquadCoeffs coeffs[EQ_NUM_BANDS];BiquadCoeffs bassCoeffs;+ Leveler leveler;float sampleRate;int numChannels;int lastCoeffVersion;@@ -40,6 +64,47 @@ typedef struct {static EQParams sParams;+static void levelerPrepare(Leveler *l, float Fs) {+ l->fastCoef = expf(-1.0f / (0.03f * Fs));+ l->followCoef = exp(-1.0 / (1.0 * Fs));+ l->dropCoef = 1.0f - expf(-1.0f / (0.01f * Fs));+ l->riseStep = powf(10.0f, 8.0f / 20.0f / Fs);+ l->fast = 0.0f;+ l->envelope = 0.0;+ l->gain = 1.0f;+}++/// The gain for one frame whose loudest channel has magnitude peak, with+/// maxGain the most the slider allows (1 = off).+static inline float levelerNext(Leveler *l, float peak, float maxGain) {+ l->fast = peak > l->fast ? peak : l->fast * l->fastCoef;+ if (l->fast >= l->envelope) {+ l->envelope = l->fast;+ } else if (l->fast > l->envelope * kLevelerPauseRatio) {+ l->envelope *= l->followCoef;+ if (l->envelope < l->fast) l->envelope = l->fast;+ }+ float wanted;+ if (l->envelope < kLevelerFloor) {+ wanted = fminf(l->gain, maxGain);+ } else {+ wanted = (float)fmin(maxGain, fmax(1.0, kLevelerTarget / l->envelope));+ }+ if (wanted < l->gain) {+ l->gain += (wanted - l->gain) * l->dropCoef;+ if (l->gain - wanted < 1e-4f) l->gain = wanted;+ } else if (wanted > l->gain) {+ l->gain = fminf(wanted, l->gain * l->riseStep);+ }+ return l->gain;+}++// The DAC clips at full scale, so the overshoot in the 10 ms before the+// gain has dropped for a sudden loud passage is clamped here.+static inline float levelerClamp(float sample) {+ return fmaxf(-1.0f, fminf(1.0f, sample));+}+/// Peaking EQ filter coefficients (constant-Q).static BiquadCoeffs peakingEQ(float f0, float dBGain, float Q, float Fs) {BiquadCoeffs c = {1, 0, 0, 0, 0};@@ -150,6 +215,7 @@ static void tapPrepare(MTAudioProcessingTapRef tap,memset(ctx->delays, 0, sizeof(ctx->delays));memset(ctx->bassDelay, 0, sizeof(ctx->bassDelay));+ levelerPrepare(&ctx->leveler, ctx->sampleRate);rebuildCoefficients(ctx);@@ -203,17 +269,20 @@ static void tapProcess(MTAudioProcessingTapRef tap,flagsOut, NULL, numberFramesOut);if (status != noErr) return;+ TapContext *ctx = (TapContext *)MTAudioProcessingTapGetStorage(tap);+ if (!ctx) return;+int bandsOn = atomic_load_explicit(&sParams.enabled, memory_order_relaxed);int mono = atomic_load_explicit(&sParams.mono, memory_order_relaxed);int loudnessMb = atomic_load_explicit(&sParams.loudnessGainMb, memory_order_relaxed);int hasBass = atomic_load_explicit(&sParams.bassBoostStrength, memory_order_relaxed) > 0;+ // With the slider back at zero the leveler eases its gain down to 1+ // before the tap goes idle, so the level never steps.+ int leveling = loudnessMb > 0 || ctx->leveler.gain > 1.0001f;// Bass / loudness / mono apply independently of the band-EQ master switch,// so process whenever any of them is active - not only when bands are on.- if (!bandsOn && !mono && loudnessMb <= 0 && !hasBass) return;-- TapContext *ctx = (TapContext *)MTAudioProcessingTapGetStorage(tap);- if (!ctx) return;+ if (!bandsOn && !mono && !leveling && !hasBass) return;int currentVersion = atomic_load_explicit(&sParams.coeffVersion, memory_order_relaxed);if (currentVersion != ctx->lastCoeffVersion) {@@ -248,14 +317,30 @@ static void tapProcess(MTAudioProcessingTapRef tap,sample = processBiquad(&ctx->bassCoeffs, &ctx->bassDelay[ch], sample);}- if (loudnessMb > 0) {- sample *= loudnessGain;- }-data[f] = sample;}}+ if (leveling) {+ float *chans[MAX_CHANNELS] = {NULL, NULL};+ for (int ch = 0; ch < totalChans; ch++) {+ chans[ch] = (float *)bufferListInOut->mBuffers[ch].mData;+ }+ for (CMItemCount f = 0; f < frames; f++) {+ float peak = 0.0f;+ for (int ch = 0; ch < totalChans; ch++) {+ if (!chans[ch]) continue;+ float magnitude = fabsf(chans[ch][f]);+ if (magnitude > peak) peak = magnitude;+ }+ float gain = levelerNext(&ctx->leveler, peak, loudnessGain);+ for (int ch = 0; ch < totalChans; ch++) {+ if (!chans[ch]) continue;+ chans[ch][f] = levelerClamp(chans[ch][f] * gain);+ }+ }+ }+if (mono && totalChans >= 2) {float *L = (float *)bufferListInOut->mBuffers[0].mData;float *R = (float *)bufferListInOut->mBuffers[1].mData;@@ -289,13 +374,22 @@ static void tapProcess(MTAudioProcessingTapRef tap,sample = processBiquad(&ctx->bassCoeffs, &ctx->bassDelay[ch], sample);}- if (loudnessMb > 0) {- sample *= loudnessGain;- }-data[f * chansInBuf + ch] = sample;}+ if (leveling) {+ float peak = 0.0f;+ for (int ch = 0; ch < chansInBuf; ch++) {+ float magnitude = fabsf(data[f * chansInBuf + ch]);+ if (magnitude > peak) peak = magnitude;+ }+ float gain = levelerNext(&ctx->leveler, peak, loudnessGain);+ for (int ch = 0; ch < chansInBuf; ch++) {+ float *sample = &data[f * chansInBuf + ch];+ *sample = levelerClamp(*sample * gain);+ }+ }+if (mono && chansInBuf >= 2) {float avg = (data[f * chansInBuf] + data[f * chansInBuf + 1]) * 0.5f;data[f * chansInBuf] = avg;diff --git a/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/GainAudioProcessor.java b/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/GainAudioProcessor.javaindex c0ab57d6..cc675048 100644--- a/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/GainAudioProcessor.java+++ b/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/GainAudioProcessor.java@@ -5,29 +5,25 @@ import androidx.media3.common.audio.BaseAudioProcessor;import java.nio.ByteBuffer;/**- * Absorb patch: the EQ loudness slider as plain sample gain inside the- * ExoPlayer audio sink, the way the iOS tap applies it. Android's- * LoudnessEnhancer is a compressor that leaves narration already peaking near- * full scale almost untouched, and it lives on the audio session, so it dies- * with the activity and on phones whose effect stack is broken. This runs on- * every sample regardless. A lookahead limiter (PeakLimiter) keeps the boosted- * peaks under full scale. With the slider at zero the audio passes through- * untouched.+ * Absorb patch: the EQ loudness slider applied inside the ExoPlayer audio+ * sink, the way the iOS tap applies it. Android's LoudnessEnhancer lives on+ * the audio session, so it dies with the activity and on phones whose effect+ * stack is broken; this runs on every sample regardless. The slider sets how+ * much gain the Leveler may add to bring quiet narration up, and a lookahead+ * limiter (PeakLimiter) keeps the result under full scale. With the slider at+ * zero the audio passes through untouched.*/public final class GainAudioProcessor extends BaseAudioProcessor {- private static final float GAIN_SMOOTH_SEC = 0.02f;-private static volatile float sGain = 1f;private PeakLimiter limiter;+ private Leveler leveler;private float[] frameIn;private float[] frameOut;private boolean is16Bit;private int frameBytes;- private float gain = 1f;- private float gainCoef;- /** Gain in millibels (100 mB = 1 dB); zero or less is unity. */+ /** The most gain the leveler may add, in millibels (100 mB = 1 dB); zero or less is off. */public static void setGainMb(int gainMb) {sGain = gainMb <= 0 ? 1f : (float) Math.pow(10.0, gainMb / 2000.0);}@@ -53,10 +49,9 @@ public final class GainAudioProcessor extends BaseAudioProcessor {is16Bit = inputAudioFormat.encoding == C.ENCODING_PCM_16BIT;frameBytes = channels * (is16Bit ? 2 : 4);limiter = new PeakLimiter(sampleRate, channels);+ leveler = new Leveler(sampleRate);frameIn = new float[channels];frameOut = new float[channels];- gain = sGain;- gainCoef = (float) (1.0 - Math.exp(-1.0 / (GAIN_SMOOTH_SEC * sampleRate)));}@Override@@ -68,10 +63,10 @@ public final class GainAudioProcessor extends BaseAudioProcessor {public void queueInput(ByteBuffer inputBuffer) {int remaining = inputBuffer.remaining();if (remaining == 0) return;- float target = sGain;+ float maxGain = sGain;// At zero the limiter stops asking for reduction and only recovers, so// a hot master is not held down with the boost off.- boolean unity = target == 1f && gain == 1f;+ boolean unity = limiter == null || (maxGain == 1f && leveler.gain() == 1f);if (limiter == null || (unity && limiter.isResting())) {// Slider at zero and the limiter has let go. Anything it still// holds goes out first so no audio is dropped.@@ -85,13 +80,15 @@ public final class GainAudioProcessor extends BaseAudioProcessor {ByteBuffer output = replaceOutputBuffer(remaining);int channels = frameIn.length;while (inputBuffer.remaining() >= frameBytes) {- // Ease toward the slider so dragging it never steps the level.- gain += (target - gain) * gainCoef;- if (Math.abs(target - gain) < 1e-4f) gain = target;+ float peak = 0f;for (int c = 0; c < channels; c++) {float sample = is16Bit ? inputBuffer.getShort() / 32768f : inputBuffer.getFloat();- frameIn[c] = sample * gain;+ frameIn[c] = sample;+ float magnitude = Math.abs(sample);+ if (magnitude > peak) peak = magnitude;}+ float gain = leveler.next(peak, maxGain);+ for (int c = 0; c < channels; c++) frameIn[c] *= gain;if (limiter.push(frameIn, frameOut, !unity)) writeFrame(output);}inputBuffer.position(inputBuffer.limit());diff --git a/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/Leveler.java b/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/Leveler.javanew file mode 100644index 00000000..138b38d7--- /dev/null+++ b/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/Leveler.java@@ -0,0 +1,79 @@+package com.ryanheise.just_audio;++/**+ * Absorb patch: the loudness slider as an automatic level, the way a car+ * radio's auto volume works. Quiet narration is pulled up toward a target+ * peak and loud narration is left alone, so every book comes out at about+ * the same level without the slider being tuned per book. The slider caps+ * how much gain may be added; at zero nothing is added.+ *+ * The level is followed on speech only. A short-term peak that sits more+ * than 30 dB under the recent level is a pause, and the gain holds through+ * it instead of creeping up and bursting on the next sentence. Gain drops+ * within 10 ms when a louder passage arrives and climbs at 8 dB a second+ * when a quieter one does.+ *+ * No Android types in here so it compiles and tests on its own.+ */+final class Leveler {+ /** Peaks are pulled up toward this level, -3 dBFS. */+ static final float TARGET = 0.708f;+ private static final float PAUSE_RATIO = 0.0316f;+ private static final float FLOOR = 0.001f;+ private static final float FAST_SEC = 0.03f;+ private static final float FOLLOW_SEC = 1.0f;+ private static final float DROP_SEC = 0.01f;+ private static final float RISE_DB_PER_SEC = 8f;++ private final float fastCoef;+ private final double followCoef;+ private final float dropCoef;+ private final float riseStep;+ private float fast;+ private double envelope;+ private float gain = 1f;++ Leveler(int sampleRate) {+ fastCoef = (float) Math.exp(-1.0 / (FAST_SEC * sampleRate));+ followCoef = Math.exp(-1.0 / (FOLLOW_SEC * sampleRate));+ dropCoef = (float) (1.0 - Math.exp(-1.0 / (DROP_SEC * sampleRate)));+ riseStep = (float) Math.pow(10.0, RISE_DB_PER_SEC / 20.0 / sampleRate);+ }++ float gain() {+ return gain;+ }++ void reset() {+ fast = 0f;+ envelope = 0;+ gain = 1f;+ }++ /**+ * The gain for one frame whose loudest channel has magnitude peak, with+ * maxGain the most the slider allows (1 = off).+ */+ float next(float peak, float maxGain) {+ fast = peak > fast ? peak : fast * fastCoef;+ if (fast >= envelope) {+ envelope = fast;+ } else if (fast > envelope * PAUSE_RATIO) {+ envelope *= followCoef;+ if (envelope < fast) envelope = fast;+ }+ float wanted;+ if (envelope < FLOOR) {+ wanted = Math.min(gain, maxGain);+ } else {+ wanted = (float) Math.min(maxGain, Math.max(1.0, TARGET / envelope));+ }+ if (wanted < gain) {+ gain += (wanted - gain) * dropCoef;+ if (gain - wanted < 1e-4f) gain = wanted;+ } else if (wanted > gain) {+ gain = Math.min(wanted, gain * riseStep);+ }+ return gain;+ }+}diff --git a/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/PeakLimiter.java b/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/PeakLimiter.javaindex 77f08d2f..b77eabae 100644--- a/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/PeakLimiter.java+++ b/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/PeakLimiter.java@@ -8,15 +8,18 @@ import java.util.Arrays;* slowly after it. Clipping the boosted samples one by one squared off every* loud syllable, which came out as static on a book mastered near full scale.* A 5 ms grab with a 200 ms recovery still dipped and bounced back on each- * word, which sounded gravelly; the slower pair holds the level through a- * phrase instead.+ * word, which sounded gravelly when this limiter was doing all the work of+ * a fixed gain. Now the Leveler ahead of it keeps peaks near -3 dBFS and the+ * limiter only catches the overshoot when a loud passage arrives, so a+ * shorter recovery no longer pumps and does not hold the level down for a+ * second after each transient.* All channels share one gain so the stereo image stays put. No Android types* in here so it compiles and tests on its own.*/final class PeakLimiter {static final float CEILING = 0.891f; // -1 dBFSprivate static final float LOOKAHEAD_SEC = 0.02f;- private static final float RELEASE_SEC = 1.0f;+ private static final float RELEASE_SEC = 0.3f;private final int channels;private final int lookahead;diff --git a/packages/just_audio/darwin/just_audio/Sources/just_audio/AudioEQProcessor.m b/packages/just_audio/darwin/just_audio/Sources/just_audio/AudioEQProcessor.mindex 72816e57..ac7ee85b 100644--- a/packages/just_audio/darwin/just_audio/Sources/just_audio/AudioEQProcessor.m+++ b/packages/just_audio/darwin/just_audio/Sources/just_audio/AudioEQProcessor.m@@ -41,6 +41,29 @@ typedef struct {_Atomic(int) coeffVersion;} EQParams;+// The loudness slider as an automatic level, the way a car radio's auto+// volume works. Quiet narration is pulled up toward a target peak and loud+// narration is left alone, so every book comes out at about the same level;+// the slider caps how much gain may be added, and at zero nothing is added.+// The level is followed on speech only: a short-term peak more than 30 dB+// under the recent level is a pause, and the gain holds through it instead+// of creeping up and bursting on the next sentence. Gain drops within 10 ms+// when a louder passage arrives and climbs at 8 dB a second when a quieter+// one does. Same algorithm as the Android Leveler in just_audio.+typedef struct {+ float fastCoef;+ double followCoef;+ float dropCoef;+ float riseStep;+ float fast;+ double envelope;+ float gain;+} Leveler;++static const float kLevelerTarget = 0.708f;+static const float kLevelerPauseRatio = 0.0316f;+static const float kLevelerFloor = 0.001f;+// ── Per-tap context (allocated in tapInit, freed in tapFinalize) ──typedef struct {@@ -48,6 +71,7 @@ typedef struct {BiquadDelay bassDelay[MAX_CHANNELS]; // bass boost shelf filterBiquadCoeffs coeffs[EQ_NUM_BANDS];BiquadCoeffs bassCoeffs;+ Leveler leveler;float sampleRate;int numChannels;int lastCoeffVersion;@@ -57,6 +81,47 @@ typedef struct {static EQParams sParams;+static void levelerPrepare(Leveler *l, float Fs) {+ l->fastCoef = expf(-1.0f / (0.03f * Fs));+ l->followCoef = exp(-1.0 / (1.0 * Fs));+ l->dropCoef = 1.0f - expf(-1.0f / (0.01f * Fs));+ l->riseStep = powf(10.0f, 8.0f / 20.0f / Fs);+ l->fast = 0.0f;+ l->envelope = 0.0;+ l->gain = 1.0f;+}++/// The gain for one frame whose loudest channel has magnitude peak, with+/// maxGain the most the slider allows (1 = off).+static inline float levelerNext(Leveler *l, float peak, float maxGain) {+ l->fast = peak > l->fast ? peak : l->fast * l->fastCoef;+ if (l->fast >= l->envelope) {+ l->envelope = l->fast;+ } else if (l->fast > l->envelope * kLevelerPauseRatio) {+ l->envelope *= l->followCoef;+ if (l->envelope < l->fast) l->envelope = l->fast;+ }+ float wanted;+ if (l->envelope < kLevelerFloor) {+ wanted = fminf(l->gain, maxGain);+ } else {+ wanted = (float)fmin(maxGain, fmax(1.0, kLevelerTarget / l->envelope));+ }+ if (wanted < l->gain) {+ l->gain += (wanted - l->gain) * l->dropCoef;+ if (l->gain - wanted < 1e-4f) l->gain = wanted;+ } else if (wanted > l->gain) {+ l->gain = fminf(wanted, l->gain * l->riseStep);+ }+ return l->gain;+}++// The DAC clips at full scale, so the overshoot in the 10 ms before the+// gain has dropped for a sudden loud passage is clamped here.+static inline float levelerClamp(float sample) {+ return fmaxf(-1.0f, fminf(1.0f, sample));+}+// ── Biquad coefficient calculation ──/// Peaking EQ filter coefficients (constant-Q).@@ -183,6 +248,7 @@ static void tapPrepare(MTAudioProcessingTapRef tap,// Zero delay linesmemset(ctx->delays, 0, sizeof(ctx->delays));memset(ctx->bassDelay, 0, sizeof(ctx->bassDelay));+ levelerPrepare(&ctx->leveler, ctx->sampleRate);// Build initial coefficientsrebuildCoefficients(ctx);@@ -256,6 +322,9 @@ static void tapProcess(MTAudioProcessingTapRef tap,int loudnessMb = atomic_load_explicit(&sParams.loudnessGainMb, memory_order_relaxed);float loudnessGain = (loudnessMb > 0) ? powf(10.0f, (float)loudnessMb / 2000.0f) : 1.0f;int hasBass = atomic_load_explicit(&sParams.bassBoostStrength, memory_order_relaxed) > 0;+ // With the slider back at zero the leveler eases its gain down to 1+ // before the pass stops, so the level never steps.+ int leveling = loudnessMb > 0 || ctx->leveler.gain > 1.0001f;UInt32 numBuffers = bufferListInOut->mNumberBuffers;CMItemCount frames = *numberFramesOut;@@ -285,15 +354,30 @@ static void tapProcess(MTAudioProcessingTapRef tap,sample = processBiquad(&ctx->bassCoeffs, &ctx->bassDelay[ch], sample);}- // Apply loudness gain- if (loudnessMb > 0) {- sample *= loudnessGain;- }-data[f] = sample;}}+ if (leveling) {+ float *chans[MAX_CHANNELS] = {NULL, NULL};+ for (int ch = 0; ch < totalChans; ch++) {+ chans[ch] = (float *)bufferListInOut->mBuffers[ch].mData;+ }+ for (CMItemCount f = 0; f < frames; f++) {+ float peak = 0.0f;+ for (int ch = 0; ch < totalChans; ch++) {+ if (!chans[ch]) continue;+ float magnitude = fabsf(chans[ch][f]);+ if (magnitude > peak) peak = magnitude;+ }+ float gain = levelerNext(&ctx->leveler, peak, loudnessGain);+ for (int ch = 0; ch < totalChans; ch++) {+ if (!chans[ch]) continue;+ chans[ch][f] = levelerClamp(chans[ch][f] * gain);+ }+ }+ }+// Mono downmix for non-interleaved stereoif (mono && totalChans >= 2) {float *L = (float *)bufferListInOut->mBuffers[0].mData;@@ -327,13 +411,22 @@ static void tapProcess(MTAudioProcessingTapRef tap,sample = processBiquad(&ctx->bassCoeffs, &ctx->bassDelay[ch], sample);}- if (loudnessMb > 0) {- sample *= loudnessGain;- }-data[f * chansInBuf + ch] = sample;}+ if (leveling) {+ float peak = 0.0f;+ for (int ch = 0; ch < chansInBuf; ch++) {+ float magnitude = fabsf(data[f * chansInBuf + ch]);+ if (magnitude > peak) peak = magnitude;+ }+ float gain = levelerNext(&ctx->leveler, peak, loudnessGain);+ for (int ch = 0; ch < chansInBuf; ch++) {+ float *sample = &data[f * chansInBuf + ch];+ *sample = levelerClamp(*sample * gain);+ }+ }+// Mono downmixif (mono && chansInBuf >= 2) {float avg = (data[f * chansInBuf] + data[f * chansInBuf + 1]) * 0.5f;