SIDMixer.java
package builder.resid;
import builder.resid.SampleMixer.LogFadingSampleMixer;
import builder.resid.SampleMixer.NoFadingSampleMixer;
import builder.resid.resample.Resampler;
import builder.resid.resample.StereoResampler;
import libsidplay.common.*;
import libsidplay.components.cart.Cartridge;
import libsidplay.components.cart.MusicCartridge;
import libsidplay.components.cart.MusicCartridgeAudioProcessor;
import libsidplay.config.IAudioSection;
import libsidplay.config.IConfig;
import libsidplay.config.ISidPlay2Section;
import libsidplay.config.IWhatsSidSection;
import libsidplay.sidtune.SidTune;
import libsidutils.oscilloscope.PlaybackTimeline;
import libsidutils.oscilloscope.ScopeSnapshot;
import libsidutils.sound.OutputSettings;
import libsidutils.sound.OutputEffects;
import sidplay.audio.AudioDriver;
import sidplay.audio.processors.AudioProcessor;
import sidplay.audio.processors.delay.DelayProcessor;
import sidplay.audio.processors.reverb.ReverbProcessor;
import sidplay.fingerprinting.WhatsSidSupport;
import java.nio.ByteBuffer;
import java.nio.IntBuffer;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import static java.lang.Short.MAX_VALUE;
import static java.lang.Short.MIN_VALUE;
import static java.nio.ByteOrder.nativeOrder;
import static libsidplay.config.ISidPlay2SystemProperties.MAX_SIDS;
/**
* Mixer to mix SIDs sample data into the audio buffer.
*
* @author ken
*
*/
public class SIDMixer implements Mixer, AudioActivitySource {
/**
* Scaler to use fast int multiplication while setting volume.
*/
static final int VOLUME_SCALER = 10;
private final PlaybackTimeline playbackTimeline = new PlaybackTimeline();
private long producedFrames, firstChunkCycle, lastOutputCycle;
private volatile long submittedFrames, playbackOriginNanos;
private int recordedSpeedMask;
private volatile long submittedCycle = Long.MIN_VALUE;
private volatile boolean warp;
private volatile long playedFrameOrigin;
private long liveStartCycle = Long.MIN_VALUE;
/**
* Change only live delivery; synthesis, resampling and cartridge processing keep running.
*/
public void setWarp(boolean enabled) {
if (warp == enabled) {
return;
}
// Partial chunks have not passed through processors yet. Consume their cartridge
// samples and advance effects before discarding output, without resetting synthesis.
if (buffer.position() > 0) {
audioProcessors.forEach(p -> p.process(buffer));
}
audioDriver.setWarp(enabled);
buffer.clear();
resetPlaybackTimeline();
liveStartCycle = context.getTime(Event.Phase.PHI2);
warp = enabled;
}
private void resetPlaybackTimeline() {
producedFrames = submittedFrames = firstChunkCycle = lastOutputCycle = 0;
submittedCycle = Long.MIN_VALUE;
playbackOriginNanos = 0;
playedFrameOrigin = Math.max(0, audioDriver.getPlayedFrames());
playbackTimeline.clear();
}
public boolean isWarp() {
return warp;
}
public PlaybackTimeline getPlaybackTimeline() {
return playbackTimeline;
}
public long getSubmittedCycle() {
return warp ? Long.MIN_VALUE : submittedCycle;
}
public void setScreenRefresh(double screenRefresh) {
this.screenRefresh = screenRefresh;
}
/**
* Budget snapshots for queued audio, not merely the latest emulation chunk.
*/
public int getScopeCapacity() {
int chunk = audioDriver.buffer().capacity() / 4;
int device = Math.max(chunk, audioDriver.getPlaybackBufferFrames());
return ScopeSnapshot.capacity(screenRefresh, config.getAudioSection().getSamplingRate().getFrequency(),
device, chunk, bufferSize, cpuClock.getCpuFrequency());
}
/**
* Prefer the device's played sample cursor. Drivers without one use a bounded wall-clock estimate; neither path may
* advance past submitted PCM samples.
*/
public long getPlaybackCycle() {
if (warp || submittedFrames == 0) {
return Long.MIN_VALUE;
}
long played = audioDriver.getPlayedFrames();
if (played >= 0) {
played = Math.max(0, played - playedFrameOrigin);
}
if (played < 0) {
if (playbackOriginNanos == 0) {
return Long.MIN_VALUE;
}
played = Math.min(submittedFrames, (long) ((System.nanoTime() - playbackOriginNanos) *
(config.getAudioSection().getSamplingRate().getFrequency() / 1e9)));
}
return playbackTimeline.cycleAt(played);
}
/**
* Publish a final partial PCM chunk using the last mixer sample, not scheduler time.
*/
public void flushAudio() throws InterruptedException {
int frames = buffer.position() / 4;
if (frames == 0) {
return;
}
// SID samples are mixed in quanta. A switch between two mixer events
// leaves part of the next quantum on the old side of the transition.
// Process it normally, but do not deliver a chunk containing old audio.
if (!warp && firstChunkCycle < liveStartCycle) {
resetPlaybackTimeline();
return;
}
playbackTimeline.add(producedFrames, lastOutputCycle);
submittedCycle = lastOutputCycle;
submittedFrames = producedFrames;
if (playbackOriginNanos == 0) {
playbackOriginNanos = System.nanoTime();
}
audioDriver.write(firstChunkCycle, lastOutputCycle, producedFrames - frames, frames);
}
/**
* The mixer mixes the generated sound samples into the drivers audio buffer.
*
* @author ken
*
*/
private final class MixerEvent extends Event {
private MixerEvent(String name) {
super(name);
}
/**
* Random source for triangular dithering
*/
private final Random RANDOM = new Random();
/**
* State of HP-TPDF.
*/
private int oldRandomValue;
/**
* Fast forward factor:<BR> fastForwardShift=1<<(VOLUME_SCALER+fastForwardFactor)
*/
private int fastForwardShift, fastForwardBitMask;
/**
* The mixer mixes the generated sound samples into the drivers audio buffer.
* <OL>
* <LI>Clock SIDs/Carts to fill audio buffer.
* <LI>Accumulate samples to implement fast forwarding.
* <LI>Resample the SID output, because the sample frequency is different to the
* clock frequency.
* <LI>Add dithering to reduce quantization noise, when moving to a format with
* less precision.
* <LI>Cut-off overflow samples.
* <LI>do some audio post-processing
* </OL>
* <B>Note:</B><BR>
* Audio buffer is cleared afterward to get refilled during next event.
*/
@Override
public void event() throws InterruptedException {
// Clock SIDs to fill the audio buffer
for (ReSIDBase sid : sids) {
// clock SID to the present moment
sid.clock();
sid.getSampler().clear();
}
// Clock cartridge to fill the audio buffer to the present moment
cart.clock();
// Read from audio buffers
int valL = 0, valR = 0;
for (int i = 0; i < bufferSize; i++) {
// Accumulate sample data with respect to a fast-forward factor
valL += audioBufferL.get();
valR += audioBufferR.get();
// once enough samples have been accumulated, write output
if ((i & fastForwardBitMask) == fastForwardBitMask) {
int dither = triangularDithering();
if (resampler.input(valL >> fastForwardShift, valR >> fastForwardShift)) {
if (recordedSpeedMask != fastForwardBitMask) {
if (producedFrames > 0) {
playbackTimeline.add(producedFrames, lastOutputCycle);
}
recordedSpeedMask = fastForwardBitMask;
}
// The scheduler is at the end of the mixing quantum.
// Anchor each PCM sample at its actual position within it.
long sampleCycle = context.getTime(Event.Phase.PHI2) - bufferSize + i + 1;
if (buffer.position() == 0) {
firstChunkCycle = producedFrames == 0 ? sampleCycle - Math.round(cpuClock.getCpuFrequency() *
(fastForwardBitMask + 1) / config.getAudioSection().getSamplingRate().getFrequency()) : lastOutputCycle;
playbackTimeline.add(producedFrames, firstChunkCycle);
}
lastOutputCycle = sampleCycle;
producedFrames++;
short outputL = (short) Math.max(Math.min(resampler.outputL() + dither, MAX_VALUE), MIN_VALUE);
buffer.putShort(outputL);
short outputR = (short) Math.max(Math.min(resampler.outputR() + dither, MAX_VALUE), MIN_VALUE);
if (!buffer.putShort(outputR).hasRemaining()) {
audioProcessors.forEach(p -> p.process(buffer));
flushAudio();
buffer.clear();
}
}
if (whatsSidEnabled) {
whatsSidSupport.output(valL >> fastForwardShift, valR >> fastForwardShift);
}
// zero accumulator
valL = valR = 0;
}
}
// Erase audio buffers
audioBufferL.flip();
audioBufferR.flip();
audioBufferL.put(emptyBuffer).clear();
audioBufferR.put(emptyBuffer).clear();
context.schedule(this, bufferSize);
}
/**
* Triangularly shaped noise source for audio applications. Output of this PRNG is between ]-1, 1[.
*
* @return triangular noise sample
*/
private int triangularDithering() {
int prevValue = oldRandomValue;
oldRandomValue = RANDOM.nextInt(2);
return oldRandomValue - prevValue;
}
}
/**
* System event context.
*/
protected final EventScheduler context;
/**
* Configuration
*/
protected final IConfig config;
/**
* CPU clock.
*/
protected final CPUClock cpuClock;
private double screenRefresh;
/**
* SIDs to mix their sound output.
*/
protected final List<ReSIDBase> sids = new ArrayList<>(MAX_SIDS);
/**
* Cartridge that could possibly add sound to the mix
*/
private final Cartridge cart;
private final MusicCartridgeAudioProcessor musicCartridgeProcessor;
private boolean audioActivityEnabled;
/**
* Mixer clocking SID chips and producing audio output.
*/
private final MixerEvent mixerAudio = new MixerEvent("MixerAudio");
/**
* Audio buffers for two channels (stereo).
*/
private IntBuffer audioBufferL, audioBufferR;
/**
* Capacity of the Audio buffers audioBufferL and audioBufferR.
*/
private int bufferSize;
private int[] emptyBuffer;
/**
* Resampler of sample output for two channels (stereo).
*/
private final StereoResampler resampler;
/**
* Audio driver
*/
private AudioDriver audioDriver;
/**
* Volume of all SIDs.
*/
private final int[] volume = new int[MAX_SIDS];
/**
* SID audibility on the left speaker of all SIDs 0(silent)..1(loud).
*/
private final float[] positionL = new float[MAX_SIDS];
/**
* SID audibility on the right speaker of all SIDs 0(silent)..1(loud).
*/
private final float[] positionR = new float[MAX_SIDS];
/**
* Delay in samples of all SIDs.
*/
private final int[] delayInSamples = new int[MAX_SIDS];
public int getSidCount() {
return sids.size();
}
/** Read existing applied state on demand; never called by the sample or CPU path. */
public OutputSettings getOutputSettings(int sidNum) {
if (sidNum < 0 || sidNum >= sids.size()) {
return null;
}
boolean mono = sids.size() == 1;
return new OutputSettings(20 * Math.log10(volume[sidNum] / (double) (1 << VOLUME_SCALER)),
mono ? .5 : positionR[sidNum], mono ? 0 : delayInSamples[sidNum] * 1000. / cpuClock.getCpuFrequency());
}
/**
* Fade-in/fade-out enabled.
*/
private final boolean fadeInFadeOutEnabled;
/**
* WhatsSid enabled?
*/
private boolean whatsSidEnabled;
/**
* WhatsSID
*/
private final WhatsSidSupport whatsSidSupport;
/**
* Add some audio post-processing.
*/
private final List<AudioProcessor> audioProcessors = new ArrayList<>();
/** On-demand copy of the same live controls used by DelayProcessor and ReverbProcessor. */
public OutputEffects getOutputEffects() {
return OutputEffects.capture(config.getAudioSection());
}
/**
* Audio driver buffer.
*/
private ByteBuffer buffer;
public SIDMixer(EventScheduler context, IConfig config, CPUClock cpuClock, Cartridge cart) {
ISidPlay2Section sidplay2Section = config.getSidplay2Section();
IAudioSection audioSection = config.getAudioSection();
IWhatsSidSection whatsSidSection = config.getWhatsSidSection();
double cpuFrequency = cpuClock.getCpuFrequency();
SamplingMethod samplingMethod = audioSection.getSampling();
int samplingFrequency = audioSection.getSamplingRate().getFrequency();
int highestAccurateFrequency = audioSection.getSamplingRate().getHighestAccurateFrequency();
this.context = context;
this.config = config;
this.cpuClock = cpuClock;
this.screenRefresh = cpuClock.getScreenRefresh();
this.cart = cart;
this.resampler = Resampler.createStereoResampler(cpuFrequency, samplingMethod, samplingFrequency, highestAccurateFrequency);
this.fadeInFadeOutEnabled = sidplay2Section.getFadeInTime() != 0 || sidplay2Section.getFadeOutTime() != 0;
this.audioProcessors.add(new DelayProcessor(config));
this.audioProcessors.add(new ReverbProcessor(config));
if (cart instanceof MusicCartridge musicCartridge) {
musicCartridgeProcessor = musicCartridge.createMusicCartridgeProcessor(this::getFastForwardBitMask, this::getFastForwardFactor);
this.audioProcessors.add(musicCartridgeProcessor);
} else {
musicCartridgeProcessor = null;
}
this.whatsSidEnabled = whatsSidSection.isEnable();
this.whatsSidSupport = new WhatsSidSupport(cpuFrequency, whatsSidSection.getCaptureTime(),
whatsSidSection.getMinimumRelativeConfidence());
normalSpeed();
}
/**
* Set the audio driver for mixing
*/
public void setAudioDriver(AudioDriver audioDriver) {
IAudioSection audioSection = config.getAudioSection();
this.audioDriver = audioDriver;
this.bufferSize = audioSection.getBufferSize();
this.emptyBuffer = new int[bufferSize];
this.buffer = audioDriver.buffer();
this.audioBufferL = ByteBuffer.allocateDirect(Integer.BYTES * bufferSize).order(nativeOrder()).asIntBuffer();
this.audioBufferR = ByteBuffer.allocateDirect(Integer.BYTES * bufferSize).order(nativeOrder()).asIntBuffer();
audioBufferL.put(emptyBuffer).clear();
audioBufferR.put(emptyBuffer).clear();
if (this.cart instanceof MusicCartridge musicCartridge) {
musicCartridge.prepare(audioSection.getSamplingRate().getFrequency(), bufferSize);
}
}
@Override
public void setAudioActivityEnabled(boolean enabled) {
if (audioActivityEnabled == enabled) return;
audioActivityEnabled = enabled;
for (int i = 0; i < sids.size(); i++) sids.get(i).setAudioActivityEnabled(enabled);
if (musicCartridgeProcessor != null) musicCartridgeProcessor.setAudioActivityEnabled(enabled);
}
@Override
public boolean pollAudioActivity() {
boolean active = false;
// Drain every source, even after finding activity, so old evidence cannot survive a poll.
for (int i = 0; i < sids.size(); i++) active |= sids.get(i).pollAudioActivity();
if (musicCartridgeProcessor != null) active |= musicCartridgeProcessor.pollAudioActivity();
return active;
}
/**
* Starts mixing the outputs of several SIDs.
*/
@Override
public void start() {
// Wait for a full quantum of chip samples. Mixing immediately would
// prepend an empty SID quantum while cartridge audio starts at time zero.
context.schedule(mixerAudio, bufferSize, Event.Phase.PHI2);
for (ReSIDBase sid : sids) {
sid.clocksSinceLastAccess();
}
if (cart instanceof MusicCartridge musicCartridge) {
musicCartridge.start();
}
}
/**
* Fade-in start time reached, audio volume should be increased to the max.
*
* @param fadeIn Fade-in time in seconds
*/
@Override
public void fadeIn(double fadeIn) {
for (ReSIDBase sid : sids) {
SampleMixer sampler = sid.getSampler();
sampler.setFadeIn((long) (fadeIn * cpuClock.getCpuFrequency()));
}
}
/**
* Fade-out start time reached, audio volume should be lowered to zero.
*
* @param fadeOut Fade-out time in seconds
*/
@Override
public void fadeOut(double fadeOut) {
for (ReSIDBase sid : sids) {
SampleMixer sampler = sid.getSampler();
sampler.setFadeOut((long) (fadeOut * cpuClock.getCpuFrequency()));
}
}
/**
* Add a SID to the mix.
*
* @param sidNum SID chip number
* @param sid SID to add
*/
public void add(SidTune tune, int sidNum, ReSIDBase sid) {
if (sidNum < sids.size()) {
sids.set(sidNum, sid);
} else {
sids.add(sid);
}
sid.setSampler(createSampleMixer(audioBufferL.duplicate(), audioBufferR.duplicate()));
sid.setAudioActivityEnabled(audioActivityEnabled);
setVolume(sidNum, config.getAudioSection().getVolume(sidNum));
if (SidTune.hasHeaderPanning(tune)) {
setBalance(sidNum, tune.getInfo().getChannel(sidNum));
} else {
setBalance(sidNum, config.getAudioSection().getBalance(sidNum));
}
setDelay(sidNum, config.getAudioSection().getDelay(sidNum));
}
/**
* Remove SID from the mix.
*
* @param sid SID to remove
*/
public void remove(ReSIDBase sid) {
sids.remove(sid);
sid.setAudioActivityEnabled(false);
sid.setSampler(null);
updateSampleMixerVolume();
}
/**
* Sets the volume of the SID chip.
* <p>
* The volume is specified in decibels (dB), which is a logarithmic unit used to describe ratios, typically of power
* or amplitude.
* </p>
* <p>
* For power ratios, decibels are calculated as:<br> {@code dB = 10 * log10(P2 / P1)}
* </p>
* <p>
* For amplitude (voltage, signal, or sample value) ratios — as used here — decibels are calculated as:<br>
* {@code dB = 20 * log10(A2 / A1)}
* </p>
* <p>
* This function assumes an amplitude-based interpretation, suitable for audio sample scaling.
* </p>
*
* @param sidNum SID chip number
* @param volumeInDB Volume adjustment in decibels, clamped to -6..6 (NaN uses 0 dB)
* @see <a href="https://www.electronics-tutorials.ws/filter/decibels.html">
* https://www.electronics-tutorials.ws/filter/decibels.html</a>
*/
@Override
public void setVolume(int sidNum, float volumeInDB) {
volumeInDB = Float.isNaN(volumeInDB) ? 0f : Math.clamp(volumeInDB, -6f, 6f);
volume[sidNum] = (int) (Math.pow(10., decibelsToCentibels(volumeInDB) / 200.) * (1 << VOLUME_SCALER));
updateSampleMixerVolume();
}
/**
* Decibel to centibel conversion.
*
* @param decibel decibel value
* @return centibel value
*/
public static int decibelsToCentibels(float decibel) {
return (int) (decibel * 10);
}
/**
* Set the left / right speaker balance for each SID.
*
* @param sidNum SID chip number
* @param balance balance clamped to 0 (left)..1 (right), with 0.5 (center) for NaN
*/
@Override
public void setBalance(int sidNum, float balance) {
balance = Float.isNaN(balance) ? 0.5f : Math.clamp(balance, 0f, 1f);
positionL[sidNum] = (1 - balance);
positionR[sidNum] = balance;
updateSampleMixerVolume();
}
/**
* Delay feature: Delaying SID chip sound samples by time in milliseconds
*
* @param sidNum SID chip number
* @param delay requested delay in ms, clamped to 0..50
*/
@Override
public void setDelay(int sidNum, int delay) {
delayInSamples[sidNum] = (int) (cpuClock.getCpuFrequency() / 1000. * Math.clamp(delay, 0, 50));
updateSampleMixerVolume();
}
/**
* Create a new sample value mixer.
*
* @param intBufferL buffer of the left speaker
* @param intBufferR buffer of the right speaker
*/
private SampleMixer createSampleMixer(IntBuffer intBufferL, IntBuffer intBufferR) {
if (fadeInFadeOutEnabled) {
return new LogFadingSampleMixer(intBufferL, intBufferR);
} else {
return new NoFadingSampleMixer(intBufferL, intBufferR);
}
}
/**
* Set the sample mixer volume to the calculated balanced volume level.<BR> Mono output: Use volume.<BR> Stereo or
* 3-SID output: Use speaker audibility and volume.
*/
private void updateSampleMixerVolume() {
boolean mono = sids.size() == 1;
boolean fakeStereo = isFakeStereo();
int sidNum = 0;
for (ReSIDBase sid : sids) {
SampleMixer sampler = sid.getSampler();
if (mono) {
sampler.setVolume(volume[sidNum], volume[sidNum]);
sampler.setDelay(0);
} else {
double leftFraction = positionL[sidNum];
double rightFraction = positionR[sidNum];
if (!fakeStereo) {
leftFraction = Math.sqrt(2 * leftFraction);
rightFraction = Math.sqrt(2 * rightFraction);
}
int volumeL = (int) (volume[sidNum] * leftFraction);
int volumeR = (int) (volume[sidNum] * rightFraction);
sampler.setVolume(volumeL, volumeR);
sampler.setDelay(delayInSamples[sidNum]);
}
sidNum++;
}
}
/**
* @return is fake stereo enabled?
*/
private boolean isFakeStereo() {
return sids.stream().map(ReSIDBase::getClass).map(Class::getSimpleName).anyMatch("FakeStereo"::equals);
}
/**
* Doubles speed factor.
*/
@Override
public void fastForward() {
mixerAudio.fastForwardShift = Math.min(mixerAudio.fastForwardShift + 1, MAX_FAST_FORWARD + VOLUME_SCALER);
mixerAudio.fastForwardBitMask = (1 << mixerAudio.fastForwardShift - VOLUME_SCALER) - 1;
}
/**
* Use normal speed factor.
*/
@Override
public void normalSpeed() {
mixerAudio.fastForwardShift = VOLUME_SCALER;
mixerAudio.fastForwardBitMask = 0;
}
@Override
public boolean isFastForward() {
return mixerAudio.fastForwardShift - VOLUME_SCALER != 0;
}
@Override
public int getFastForwardBitMask() {
return mixerAudio.fastForwardBitMask;
}
public int getFastForwardFactor() {
return mixerAudio.fastForwardShift - VOLUME_SCALER;
}
public WhatsSidSupport getWhatsSidSupport() {
return whatsSidSupport;
}
public void setWhatsSidEnabled(boolean whatsSidEnabled) {
this.whatsSidEnabled = whatsSidEnabled;
}
}