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&lt;&lt;(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;
    }

}