Player.java

/**
 * This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public
 * License as published by the Free Software Foundation; either version 2 of the License or (at your option) any later
 * version.
 *
 * @author Ken Händel
 *
 */
package sidplay;

import builder.SIDBuilderFactory;
import builder.resid.SIDMixer;
import libsidplay.HardwareEnsemble;
import libsidplay.common.*;
import libsidplay.common.Event.Phase;
import libsidplay.components.c1530.Datasette.Control;
import libsidplay.components.cart.Cartridge;
import libsidplay.components.cart.CartridgeType;
import libsidplay.components.mos6510.IMOS6510Extension;
import libsidplay.components.mos6510.MOS6510;
import libsidplay.components.mos6526.MOS6526;
import libsidplay.components.mos656x.VIC;
import libsidplay.config.IAudioSection;
import libsidplay.config.IConfig;
import libsidplay.config.IEmulationSection;
import libsidplay.config.ISidPlay2Section;
import libsidplay.sidtune.AudioTune;
import libsidplay.sidtune.SidTune;
import libsidplay.sidtune.SidTuneError;
import libsidutils.debug.InspectionService;
import libsidutils.fingerprinting.IFingerprintMatcher;
import libsidutils.fingerprinting.rest.beans.MusicInfoWithConfidenceBean;
import libsidutils.siddatabase.SidDatabase;
import libsidutils.stil.STIL.STILEntry;
import libsidutils.stil.STIL;
import sidplay.audio.Audio;
import sidplay.audio.AudioDriver;
import sidplay.audio.AudioDriverFactory;
import sidplay.audio.VideoDriver;
import sidplay.audio.exceptions.IniConfigException;
import sidplay.audio.exceptions.SongEndException;
import sidplay.ini.IniConfig;
import sidplay.player.*;

import javax.sound.sampled.LineUnavailableException;
import java.beans.PropertyChangeListener;
import java.io.File;
import java.io.IOException;
import java.lang.Thread.UncaughtExceptionHandler;
import java.net.URL;
import java.util.AbstractMap.SimpleImmutableEntry;
import java.util.Calendar;
import java.util.Date;
import java.util.List;
import java.util.Objects;
import java.util.concurrent.CopyOnWriteArrayList;
import java.util.concurrent.atomic.AtomicReference;
import java.util.function.*;
import java.util.logging.Level;
import java.util.logging.Logger;

import static java.lang.String.format;
import static libsidplay.common.SIDEmu.NONE;
import static libsidplay.config.ISidPlay2SystemProperties.MAX_SONG_LENGTH;
import static libsidplay.sidtune.SidTune.RESET;
import static libsidutils.IOUtils.ioWrap;
import static sidplay.AllRoms.*;
import static sidplay.ini.IniDefaults.DEFAULT_AUDIO;
import static sidplay.ini.IniDefaults.DEFAULT_TMP_DIR;
import static sidplay.player.State.*;

/**
 * The player adds some music player capabilities to the HardwareEnsemble.
 *
 * @author Ken Händel
 *
 */
public class Player extends HardwareEnsemble implements VideoDriver, SIDListener, IMOS6510Extension {

    private static final Logger LOG = Logger.getLogger(Player.class.getName());

    private static final AudioDriverFactory DEFAULT_AUDIO_DRIVER_FACTORY =
            (audioSection, tune) -> audioSection.getAudio().create(audioSection, tune);

    /**
     * Build date calculated from our own modified time
     */
    public static final Calendar LAST_MODIFIED;

    static {
        try {
            URL us = Player.class.getProtectionDomain().getCodeSource().getLocation();
            LAST_MODIFIED = Calendar.getInstance();
            LAST_MODIFIED.setTime(new Date(us.openConnection().getLastModified()));
        } catch (IOException e) {
            throw new ExceptionInInitializerError(e);
        }
    }

    /**
     * Timeout (in ms) for sleeping, if the player is paused.
     */
    private static final int PAUSE_SLEEP_TIME = 250;
    /**
     * Timeout (in ms) for quitting the player.
     */
    private static final int QUIT_MAX_WAIT_TIME = 1000;

    /**
     * Previous song select timeout (< 4 secs).
     */
    private static final int PREV_SONG_TIMEOUT = 4;
    /**
     * Auto-start commands.
     */
    private static final String RUN = "RUN\r", SYS = "SYS%d\r", LOAD = "LOAD\r";

    /**
     * Music player state.
     */
    private ObjectProperty<State> stateProperty;
    /**
     * Play timer.
     */
    private Timer timer;
    /**
     * Play list.
     */
    private PlayList playList;
    /**
     * Currently played tune.
     */
    private SidTune tune;
    /**
     * Auto-start command to be typed-in after reset (PETSCII).
     */
    private String command;
    /**
     * Music player thread.
     */
    private Thread playerThread;
    private final ObjectProperty<String> inspectionStatus = new ObjectProperty<>("Inspection", "OFF");
    /**
     * Called each time a tune starts to play.
     */
    private Consumer<Player> menuHook = player -> {
    };
    /**
     * Called each time a chunk of music has been played.
     */
    private Consumer<Player> interactivityHook = player -> {
    };
    /**
     * Called after WhatsSID has detected a tune.
     */
    private Consumer<MusicInfoWithConfidenceBean> whatsSidHook = musicInfoWithConfidence -> {
    };
    /**
     * Override the player address of the tune.
     */
    private Function<Integer, Integer> playAddrHook = Function.identity();

    /**
     * Currently used audio and corresponding audio driver.
     * <p>
     * <B>Note:</B> If an audio driver has been set externally by
     * {@link Player#setAudioDriver(AudioDriver)} or a custom
     * {@link Player#setAudioDriverFactory(AudioDriverFactory)}, audio is null!
     */
    private SimpleImmutableEntry<Audio, AudioDriver> audioAndDriver;

    private AudioDriverFactory audioDriverFactory = DEFAULT_AUDIO_DRIVER_FACTORY;

    /**
     * Uncaught Player exception handler.
     */
    private UncaughtExceptionHandler uncaughtExceptionHandler;

    /**
     * Check the default length in record mode (default is true).
     * <p>
     * <B>Note:</B> In record mode the player requires a default length. If it is
     * not available, it will be limited to 180s.
     */
    private boolean checkDefaultLengthInRecordMode;
    /**
     * Set the check loop off in record mode (default is true).
     * <p>
     * <B>Note:</B> In record mode the player must not loop forever. However, it can
     * be forced to not be checked.
     */
    private boolean checkLoopOffInRecordMode;
    /**
     * Force check song length (default is false).
     * <p>
     * <B>Note:</B> If song length has been reached, the player ends the current
     * song, but not in RESET mode. However, this can be forced by this switch.
     */
    private boolean forceCheckSongLength;

    /**
     * Autodetection of SID chip configuration.
     */
    private final Autodetection autodetection;

    /**
     * The first entry of the playlist is the first song (otherwise start song).
     */
    private boolean firstPlayListEntryIsOne;
    /**
     * SID builder being used to create SID chips (real hardware or emulation).
     */
    private SIDBuilder sidBuilder;
    private Cartridge automaticSoundExpander;
    /**
     * SID tune information list.
     */
    private STIL stil;
    /**
     * Song length database.
     */
    private SidDatabase sidDatabase;
    /**
     * Create a base name of a filename to be used for recording.
     */
    private Function<SidTune, String> recordingFilenameProvider;
    /**
     * Insert required SIDs. Use SID builder to create/destroy SIDs.
     */
    private final BiFunction<Integer, SIDEmu, SIDEmu> requiredSIDs = (sidNum, sidEmu) -> {
        if (SidTune.isSIDUsed(config.getEmulationSection(), tune, sidNum)) {
            return sidBuilder.lock(sidEmu, sidNum, tune);
        } else if (sidEmu != NONE) {
            sidBuilder.unlock(sidEmu);
        }
        return NONE;
    };
    /**
     * Eject all SIDs.
     */
    private final BiFunction<Integer, SIDEmu, SIDEmu> noSIDs = (sidNum, sidEmu) -> {
        if (sidEmu != NONE) {
            sidBuilder.unlock(sidEmu);
        }
        return NONE;
    };
    /**
     * Set the base address of required SIDs.
     */
    private final IntFunction<Integer> sidLocator = sidNum -> SidTune.getSIDAddress(config.getEmulationSection(), tune,
            sidNum);
    /**
     * Player paused? Stop audio production.
     */
    private final PropertyChangeListener pauseListener = event -> {
        if (event.getNewValue() == PAUSE) {
            getAudioDriver().pause();
            configureMixer(Mixer::pause);
            // audio driver continues automatically, next call of write()!
        }
    };

    /**
     * Consumer for VIC screen output as ARGB data
     */
    private final List<VideoDriver> videoDrivers = new CopyOnWriteArrayList<>();

    /**
     * Consumer for SID register writes
     */
    private final List<SIDListener> sidListeners = new CopyOnWriteArrayList<>();

    /**
     * Consumer for CPU JMP/JSR instructions
     */
    private final List<IMOS6510Extension> mos6510Extensions = new CopyOnWriteArrayList<>();

    /**
     * Fast-forward: skipped VIC frames.
     */
    private int fastForwardVICFrames;

    private final ObjectProperty<Boolean> warpProperty = new ObjectProperty<>("WARP", false);
    private final WarpControl warpControl;
    private final AutostartControl autostartControl;
    private final LongSupplier warpTime;
    private volatile boolean warpSupported;
    private long nextWarpFrameNanos;
    private boolean cartridgeBoot;

    /**
     * WhatsSID?
     */
    private IFingerprintMatcher fingerPrintMatcher;

    /**
     * Regularly scheduled event for tune recognition.
     */
    private WhatsSidEvent whatsSidEvent;

    /**
     * Create a Music Player.
     *
     * @param config configuration
     */
    public Player(final IConfig config) {
        this(config, System::nanoTime);
    }

    Player(final IConfig config, LongSupplier warpTime) {
        super(config, CHAR, BASIC, KERNAL, JIFFYDOS_C64, JIFFYDOS_C1541, JIFFYDOS_C1571, JIFFYDOS_C1581,
                C1541, C1541_II, C1571, C1581, MPS803_CHAR);
        this.warpTime = warpTime;
        warpControl = new WarpControl(warpTime, this::applyWarp);
        autostartControl = new AutostartControl(c64, this::typeInCommand, warpControl::finishStartup);
        initializeTmpDir(config);
        stateProperty = new ObjectProperty<>(State.class.getSimpleName(), QUIT);
        audioAndDriver = new SimpleImmutableEntry<>(DEFAULT_AUDIO, DEFAULT_AUDIO.getAudioDriver());
        checkDefaultLengthInRecordMode = true;
        checkLoopOffInRecordMode = true;
        forceCheckSongLength = false;
        firstPlayListEntryIsOne = false;
        recordingFilenameProvider = tune -> new File(config.getSidplay2Section().getTmpDir(), "jsidplay2")
                .getAbsolutePath();
        this.playList = new PlayList(config.getSidplay2Section(), RESET, firstPlayListEntryIsOne);
        this.timer = new Timer(config.getSidplay2Section(), c64.getEventScheduler(),
                () -> getSidDatabaseInfo(db -> db.getSongLength(tune), 0.)) {

            @Override
            protected long getInitDelay(SidTune tune) {
                return cartridgeBoot ? 0 : super.getInitDelay(tune);
            }

            /**
             * Start time reached?
             *
             * @see sidplay.player.Timer#start()
             */
            @Override
            public void start() {
                c64.insertSIDChips(requiredSIDs, sidLocator);
                c64.configureVICs(vic -> vic.setVideoDriver(Player.this));
                c64.setSIDListener(Player.this);
                c64.setPlayRoutineObserver(Player.this);
                configureMixer(Mixer::start);

                if (whatsSidEvent != null) {
                    whatsSidEvent.start();
                }
            }

            /**
             * If a tune ends, there are these possibilities:
             * <OL>
             * <LI>Play next song (except singles)
             * <LI>Play again looping song (except recordings)
             * <LI>End tune
             * </OL>
             *
             * @see sidplay.player.Timer#end()
             */
            @Override
            public void end() {
                ISidPlay2Section sidplay2Section = config.getSidplay2Section();

                if (!sidplay2Section.isSingle() && playList.hasNext()) {
                    nextSong();
                } else if (sidplay2Section.isLoop()) {
                    if (checkLoopOffInRecordMode && getAudioDriver().isRecording()) {
                        stateProperty.set(END);
                        System.out.println("Warning: Loop has been disabled during recording!");
                    } else {
                        stateProperty.set(RESTART);
                    }
                } else {
                    stateProperty.set(END);
                }
            }

            /**
             * If a tune starts playing, fade-in volume.
             *
             * @see sidplay.player.Timer#fadeInStart(double)
             */
            @Override
            public void fadeInStart(final double fadeIn) {
                configureMixer(mixer -> mixer.fadeIn(fadeIn));
            }

            /**
             * If a tune is short before stop time, fade-out volume.
             *
             * @see sidplay.player.Timer#fadeOutStart(double)
             */
            @Override
            public void fadeOutStart(final double fadeOut) {
                configureMixer(mixer -> mixer.fadeOut(fadeOut));
            }

        };
        autodetection = new Autodetection(config.getEmulationSection(), c64, timer) {
            @Override
            protected AudioActivitySource getAudioActivitySource() {
                return sidBuilder instanceof AudioActivitySource source ? source : null;
            }

            @Override
            protected void updateSids() {
                updateSIDChipConfiguration();
            }
        };
    }

    /**
     * Create temporary directory, if it does not exist.<BR> E.g. Recordings and converted tapes are saved here!
     */
    public static void initializeTmpDir(IConfig config) {
        File tmpDir = config.getSidplay2Section().getTmpDir();
        if (tmpDir == null) {
            // non-existent file is nulled, but tmpDir is mandatory!
            tmpDir = DEFAULT_TMP_DIR;
            config.getSidplay2Section().setTmpDir(tmpDir);
        }
        if (!tmpDir.exists()) {
            ioWrap(tmpDir::mkdirs);
        }
    }

    /**
     * Get a fingerprint matcher.
     *
     * @return fingerprint matcher
     */
    public IFingerprintMatcher getFingerPrintMatcher() {
        return fingerPrintMatcher;
    }

    /**
     * Set a fingerprint matcher.
     *
     * @param fingerPrintMatcher a fingerprint matcher
     */
    public void setFingerPrintMatcher(IFingerprintMatcher fingerPrintMatcher) {
        this.fingerPrintMatcher = fingerPrintMatcher;
    }

    /**
     * Call to update SID chips each time SID configuration has been changed thread-safe.
     */
    public final void updateSIDChipConfiguration() {
        executeInPlayerThread("Update SID Chip Configuration", () -> c64.insertSIDChips(requiredSIDs, sidLocator));
    }

    /**
     * Call to configure VIC chips thread-safe.
     *
     * @param action VIC configuration action
     */
    public final void configureVICs(Consumer<VIC> action) {
        executeInPlayerThread("Configure VICs", () -> c64.configureVICs(action));
    }

    /**
     * Configure all available SIDs thread-safe.
     *
     * @param action SID chip consumer
     */
    public final void configureSIDs(BiConsumer<Integer, SIDEmu> action) {
        executeInPlayerThread("Configure SIDs", () -> c64.configureSIDs(action));
    }

    /**
     * Configure one specific SID thread-safe.
     *
     * @param chipNum SID chip number
     * @param action  SID chip consumer
     */
    public final void configureSID(int chipNum, Consumer<SIDEmu> action) {
        executeInPlayerThread("Configure SID", () -> c64.configureSID(chipNum, action));
    }

    /**
     * Configure the mixer, optionally implemented by SID builder thread-safe.
     *
     * @param action mixer consumer
     */
    public final void configureMixer(final Consumer<Mixer> action) {
        executeInPlayerThread("Configure Mixer", () -> {
            if (sidBuilder instanceof Mixer) {
                action.accept((Mixer) sidBuilder);
            }
        });
    }

    /**
     * Complete a drive mutation on the emulation thread before returning to its caller.
     *
     * @param mutation drive operation
     * @throws IOException operation failed, was interrupted or timed out
     */
    @Override
    protected void mutateDrive(DriveMutation mutation) throws IOException {
        if (playerThread == null || !playerThread.isAlive() || Thread.currentThread() == playerThread) {
            mutation.run();
            return;
        }
        java.util.concurrent.CompletableFuture<Void> completion = new java.util.concurrent.CompletableFuture<>();
        executeInPlayerThread("Change floppy media", () -> {
            try {
                mutation.run();
                completion.complete(null);
            } catch (Throwable error) {
                completion.completeExceptionally(error);
            }
        });
        try {
            completion.get(30, java.util.concurrent.TimeUnit.SECONDS);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new IOException("Drive change interrupted", e);
        } catch (java.util.concurrent.ExecutionException e) {
            if (e.getCause() instanceof IOException io) throw io;
            throw new IOException("Drive change failed", e.getCause());
        } catch (java.util.concurrent.TimeoutException e) {
            throw new IOException("Player did not process drive change", e);
        }
    }

    /**
     * Execute immediately on the player thread, or schedule the operation from another thread.
     *
     * @param eventName scheduled event name
     * @param runnable  operation to execute on the player thread
     */
    private void executeInPlayerThread(String eventName, Runnable runnable) {
        if (Thread.currentThread().equals(playerThread)) {
            runnable.run();
        } else {
            c64.getEventScheduler().scheduleThreadSafe(Event.of(eventName, event -> runnable.run()));
        }
    }

    /** Configure optional tooling on the emulation thread, including while playback is paused. */
    public void inspect(Consumer<InspectionService> action) {
        Runnable configure = () -> {
            InspectionService service = c64.getInspection();
            service.setPauseHandler(snapshot -> stateProperty.set(PAUSE));
            service.setStatusListener(inspectionStatus::set);
            action.accept(service);
        };
        if (playerThread == null || !playerThread.isAlive()) {
            configure.run();
        } else {
            executeInPlayerThread("Configure inspection", configure);
        }
    }

    public ObjectProperty<String> inspectionStatusProperty() {
        return inspectionStatus;
    }

    /**
     * Power-on C64 system.
     */
    @Override
    public final void reset() {
        final IEmulationSection emulationSection = config.getEmulationSection();

        autostartControl.cancel();
        cartridgeBoot = AutostartControl.isCartridgeBoot(c64, tune == RESET, command);
        super.reset();

        if (emulationSection.getUltimate64Mode() != Ultimate64Mode.OFF && tune == RESET) {
            sendReset(config, RESET);
        }
        c64.getEventScheduler().schedule(Event.of("Auto-start", event -> {
            if (tune != RESET) {
                // for tunes: Install player into RAM
                Integer driverAddress = tune.placeProgramInMemory(c64.getRAM());
                if (driverAddress != null) {
                    if (emulationSection.getUltimate64Mode() != Ultimate64Mode.OFF) {
                        sendRamAndSys(config, tune, c64.getRAM(), driverAddress);
                    }
                    if (emulationSection.getUltimate64Mode() != Ultimate64Mode.STANDALONE) {
                        // Set play address to feedback call frames counter.
                        c64.setPlayAddr(playAddrHook.apply(tune.getInfo().getPlayAddr()));
                        // Start SID player driver
                        c64.getCPU().forcedJump(driverAddress);
                    }
                } else {
                    // No player: Start basic program or assembler code
                    final int loadAddr = tune.getInfo().getLoadAddr();
                    if (emulationSection.getUltimate64Mode() != Ultimate64Mode.OFF) {
                        if (loadAddr == 0x0801) {
                            sendRamAndRun(config, tune, c64.getRAM());
                        } else {
                            sendRamAndSys(config, tune, c64.getRAM(), loadAddr);
                        }
                    }
                    command = loadAddr == 0x0801 ? RUN : loadAddr >= 0x0801 ? format(SYS, loadAddr) : null;
                }
            }
            if (command != null) {
                if (command.startsWith(LOAD)) {
                    // Load from tape needs someone to press play
                    datasette.control(Control.START);
                }
                // Enter basic command
                if (emulationSection.getUltimate64Mode() != Ultimate64Mode.STANDALONE) {
                    if (tune != RESET || !autostartControl.start(command)) {
                        warpControl.finishStartup();
                        typeInCommand(command);
                    }
                }
                if (emulationSection.getUltimate64Mode() != Ultimate64Mode.OFF && tune == RESET) {
                    sendWait(config, 300);
                    sendCommand(config, command);
                }
            }
            if (tune != RESET || command == null || !AutostartControl.isLoadCommand(command)) {
                warpControl.finishStartup();
            }
            autodetection.start(tune);
        }), cartridgeBoot ? 0 : SidTune.getInitDelay(tune));
    }

    /**
     * Enter a basic command after reset (PETSCII).
     *
     * @param command basic command after reset
     */
    private void setCommand(final String command) {
        this.command = command;
    }

    /**
     * What is the current playing time in secs?
     *
     * @return the current playing time in secs
     */
    public final double time() {
        final EventScheduler c = c64.getEventScheduler();
        long initDelay = SidTune.getInitDelay(tune);
        return (c.getTime(Phase.PHI2) - initDelay) / c.getCyclesPerSecond();
    }

    /**
     * Get the current playlist.
     *
     * @return current tune-based playlist
     */
    public final PlayList getPlayList() {
        return playList;
    }

    /**
     * Get the current timer.
     *
     * @return song length timer
     */
    public final Timer getTimer() {
        return timer;
    }

    /**
     * Get the currently played tune.
     *
     * @return the currently played tune
     */
    public final SidTune getTune() {
        return tune;
    }

    /**
     * Set a tune to play.
     *
     * @param tune tune to play
     */
    public final void setTune(final SidTune tune) {
        this.tune = tune;
    }

    /**
     * Start a player thread.
     */
    public synchronized final void startC64() {
        if (playerThread == null || !playerThread.isAlive()) {
            playerThread = new Thread(playerRunnable, "Player");
            playerThread.setPriority(Thread.MAX_PRIORITY);
            playerThread.setUncaughtExceptionHandler(uncaughtExceptionHandler);
            playerThread.start();
        }
    }

    /**
     * Stop player thread.
     */
    public final void stopC64() {
        stopC64(true);
    }

    /**
     * Stop or wait for player thread.
     *
     * @param quitOrWait quit player (true) or wait for termination, only (false)
     */
    public synchronized final void stopC64(final boolean quitOrWait) {
        try {
            while (playerThread != null && playerThread.isAlive()) {
                if (quitOrWait) {
                    quit();
                }
                playerThread.join(QUIT_MAX_WAIT_TIME);
            }
        } catch (InterruptedException ignored) {
        }
    }

    /**
     * Set a hook to be called when the player has opened a tune.
     *
     * @param menuHook menu hook
     */
    public final void setMenuHook(final Consumer<Player> menuHook) {
        this.menuHook = menuHook;
    }

    /**
     * Set a hook to be called when the player has played a chunk.
     *
     * @param interactivityHook interactivity hook
     */
    public final void setInteractivityHook(final Consumer<Player> interactivityHook) {
        this.interactivityHook = interactivityHook;
    }

    /**
     * Get a hook to be called when WhatsSid has detected a tune.
     *
     * @return hook to be called when WhatsSid has detected a tune
     */
    public Consumer<MusicInfoWithConfidenceBean> getWhatsSidHook() {
        return whatsSidHook;
    }

    /**
     * Set a hook to be called when WhatsSid has detected a tune.
     *
     * @param whatsSidHook hook to be called when WhatsSid has detected a tune
     */
    public void setWhatsSidHook(Consumer<MusicInfoWithConfidenceBean> whatsSidHook) {
        this.whatsSidHook = whatsSidHook;
    }

    /**
     * Set a hook to be called when the player address has been read from the tune.
     *
     * @param playAddrHook player address hook
     */
    public void setPlayAddrHook(Function<Integer, Integer> playAddrHook) {
        this.playAddrHook = playAddrHook;
    }

    /**
     * Get the player's state.
     *
     * @return the player's state
     */
    public final ObjectProperty<State> stateProperty() {
        return stateProperty;
    }

    /**
     * Get the effective WARP state property.
     */
    public ObjectProperty<Boolean> warpProperty() {
        return warpProperty;
    }

    public boolean isWarp() {
        return warpControl.isActive();
    }

    public boolean isWarpSupported() {
        return warpSupported;
    }

    /**
     * Manual requests override startup automation and its timeout.
     */
    public void setWarp(boolean enabled) {
        executeInPlayerThread("Set WARP", () -> {
            if (!enabled || warpSupported) {
                warpControl.setManual(enabled);
            }
        });
    }

    private void applyWarp(boolean enabled) {
        if (sidBuilder instanceof SIDMixer mixer) {
            mixer.setWarp(enabled);
        }
        nextWarpFrameNanos = 0;
        videoDrivers.forEach(VideoDriver::clearQueuedFrames);
        warpProperty.set(enabled);
    }

    /**
     * Player runnable to play music in a background thread.
     */
    private final Runnable playerRunnable = () -> {
        // Run until the player gets stopped
        playList = new PlayList(config.getSidplay2Section(), tune, firstPlayListEntryIsOne);
        do {
            try {
                stateProperty.set(OPEN);
                open();
                stateProperty.set(START);
                menuHook.accept(Player.this);
                stateProperty.set(PLAY);
                // Play next chunk of sound data
                while (play()) {
                    interactivityHook.accept(Player.this);
                }
            } catch (SongEndException e) {
                timer.end();
            } catch (IniConfigException e) {
                System.err.println(e.getMessage());
                stateProperty.set(RESTART);
                e.getConfigRepairer().run();
            } catch (InterruptedException | IOException | LineUnavailableException | RuntimeException
                     | UnsatisfiedLinkError e) {
                stateProperty.set(QUIT);
                throw new RuntimeException(e.getMessage(), e);
            } finally {
                close();
            }
            // "Play it once, Sam. For old times' sake."
        } while (stateProperty.get() == RESTART);
    };

    /**
     * Open player, creating its next audio output through the configured factory.
     *
     * @throws LineUnavailableException audio line currently in use
     * @throws IOException              audio output file cannot be written
     * @throws InterruptedException     thread interrupted
     */
    private void open() throws IOException, LineUnavailableException, InterruptedException {
        final ISidPlay2Section sidplay2Section = config.getSidplay2Section();
        final IEmulationSection emulationSection = config.getEmulationSection();
        final IAudioSection audioSection = config.getAudioSection();

        fastForwardVICFrames = 0;
        playList.prepare();
        stateProperty.addListener(pauseListener);

        setClock(CPUClock.getCPUClock(emulationSection, tune, getC64().getVicModel()));

        reset();

        Audio audio = audioDriverFactory == DEFAULT_AUDIO_DRIVER_FACTORY ? audioSection.getAudio() : null;
        // A failed factory must not leave the previously closed output active.
        setAudioAndDriver(audio, null);
        setAudioAndDriver(audio, Objects.requireNonNull(audioDriverFactory.create(audioSection, tune),
                "Audio driver factory returned null"));

        timer.setStart(sidplay2Section.getStartTime());
        timer.setDefaultLength(config.getSidplay2Section().getDefaultPlayLength());
        timer.setForceCheckSongLength(forceCheckSongLength);
        verifyConfiguration();
        timer.reset(tune);

        if (getAudioDriver() instanceof VideoDriver) {
            addVideoDriver((VideoDriver) getAudioDriver());
        }
        if (getAudioDriver() instanceof SIDListener) {
            addSidListener((SIDListener) getAudioDriver());
        }
        if (getAudioDriver() instanceof IMOS6510Extension) {
            addMOS6510Extension((IMOS6510Extension) getAudioDriver());
        }
        getAudioDriver().setVideoTiming(c64.getScreenRefresh(), c64.getVIC().getBorderHeight());
        getAudioDriver().open(audioSection, getRecordingFilename(), c64.getClock(), c64.getEventScheduler());

        configureSoundExpander(SidTune.isFMOpl(config.getEmulationSection(), tune));
        sidBuilder = createSIDBuilder(c64.getClock());

        if (sidBuilder instanceof SIDMixer) {
            SIDMixer sidMixer = (SIDMixer) sidBuilder;
            sidMixer.setScreenRefresh(c64.getScreenRefresh());
            sidMixer.setAudioDriver(getAudioDriver());
            whatsSidEvent = new WhatsSidEvent(Player.this, sidMixer.getWhatsSidSupport());
        }
        // Real devices and recording/comparison/streaming drivers have their own
        // timing contracts. Only an explicitly capable live sink may bypass pacing.
        warpSupported = sidBuilder instanceof SIDMixer && getAudioDriver().supportsWarp()
                && !getAudioDriver().isRecording() && !(tune instanceof AudioTune)
                && emulationSection.getUltimate64Mode() == Ultimate64Mode.OFF;
        if (warpSupported && sidplay2Section.isWarpOnStartup() && !cartridgeBoot) {
            warpControl.start(sidplay2Section.getWarpStartupTimeout());
        }
    }

    /**
     * Keep tune-managed FM hardware from leaking into subsequent SID-only playback.
     */
    void configureSoundExpander(boolean fmOpl) throws IOException {
        if (fmOpl) {
            insertCartridge(CartridgeType.SOUNDEXPANDER, 1);
            automaticSoundExpander = c64.getCartridge();
        } else {
            if (automaticSoundExpander != null && c64.getCartridge() == automaticSoundExpander) {
                c64.ejectCartridge();
            }
            automaticSoundExpander = null;
        }
    }

    /**
     * Create a configured SID chip implementation (software/hardware).
     *
     * @param cpuClock CPU clock frequency
     * @return SID builder
     */
    private SIDBuilder createSIDBuilder(final CPUClock cpuClock) {
        return SIDBuilderFactory.create(Engine.getEngine(config.getEmulationSection(), tune),
                c64.getEventScheduler(), config, cpuClock, c64.getCartridge(), c64.getCyclesPerFrame());
    }

    public SIDBuilder getSidBuilder() {
        return sidBuilder;
    }

    /**
     * Check the configuration.
     */
    private void verifyConfiguration() {
        if (checkDefaultLengthInRecordMode && getAudioDriver().isRecording()
                && getSidDatabaseInfo(db -> db.getSongLength(tune), 0.) == 0
                && config.getSidplay2Section().getDefaultPlayLength() == 0) {
            timer.setDefaultLength(MAX_SONG_LENGTH);
            System.out.printf("Unknown song length in record mode, using %d\n", MAX_SONG_LENGTH);
        }
        if (getAudioDriver().requiresPlayAddress()
                && (tune == RESET || tune.getInfo().getPlayAddr() == 0)) {
            throw new RuntimeException("SIDDump audio driver requires a well-known player address of the tune");
        }
    }

    /**
     * Get Audio of an audio driver or null for custom audio drivers.
     *
     * @return audio audio
     */
    public Audio getAudio() {
        return audioAndDriver.getKey();
    }

    /**
     * Get currently used audio driver.
     *
     * @return currently used audio driver
     */
    public AudioDriver getAudioDriver() {
        return this.audioAndDriver.getValue();
    }

    /**
     * Use a fixed audio driver for subsequent playbacks. Configure it before
     * starting playback or after {@link #stopC64()} returns. The player opens and
     * closes this same instance for each playback. Use
     * {@link #setAudioDriverFactory(AudioDriverFactory)} when a new instance is required.
     *
     * @param audioDriver alternative audio driver, never {@code null}
     */
    public final void setAudioDriver(final AudioDriver audioDriver) {
        Objects.requireNonNull(audioDriver, "audioDriver");
        audioDriverFactory = (audioSection, tune) -> audioDriver;
        setAudioAndDriver(null, audioDriver);
    }

    /**
     * Create audio drivers at the start of each playback. Configure the factory
     * before starting playback or after {@link #stopC64()} returns. The player
     * manages opening and closing each returned driver.
     *
     * @param factory custom factory, or {@code null} to restore the configured
     *                built-in audio selection
     */
    public final void setAudioDriverFactory(final AudioDriverFactory factory) {
        audioDriverFactory = factory != null ? factory : DEFAULT_AUDIO_DRIVER_FACTORY;
        setAudioAndDriver(factory == null ? config.getAudioSection().getAudio() : null, getAudioDriver());
    }

    /**
     * Set audio for the play-back
     *
     * @param audio audio for play-back
     */
    private void setAudioAndDriver(final Audio audio, final AudioDriver audioDriver) {
        this.audioAndDriver = new SimpleImmutableEntry<>(audio, audioDriver);
    }

    /**
     * Set an uncaught Player exception handler.
     *
     * @param uncaughtExceptionHandler excdeption handler
     */
    public void setUncaughtExceptionHandler(UncaughtExceptionHandler uncaughtExceptionHandler) {
        this.uncaughtExceptionHandler = uncaughtExceptionHandler;
    }

    /**
     * Set check default length in record mode (default is true).
     *
     * @param checkDefaultLengthInRecordMode check the default length in record mode
     */
    public void setCheckDefaultLengthInRecordMode(boolean checkDefaultLengthInRecordMode) {
        this.checkDefaultLengthInRecordMode = checkDefaultLengthInRecordMode;
    }

    /**
     * Set the check loop off in record mode (default is true).
     *
     * @param checkLoopOffInRecordMode check loop off in record mode
     */
    public void setCheckLoopOffInRecordMode(boolean checkLoopOffInRecordMode) {
        this.checkLoopOffInRecordMode = checkLoopOffInRecordMode;
    }

    /**
     * Set force check song length (default is false).
     *
     * @param forceCheckSongLength force check song length
     */
    public void setForceCheckSongLength(boolean forceCheckSongLength) {
        this.forceCheckSongLength = forceCheckSongLength;
    }

    /**
     * Set first entry of the playlist is the first song (otherwise start song).
     *
     * @param firstPlayListEntryIsOne The first entry of the playlist is the first song (otherwise start song)
     */
    public void setFirstPlayListEntryIsOne(boolean firstPlayListEntryIsOne) {
        this.firstPlayListEntryIsOne = firstPlayListEntryIsOne;
    }

    /**
     * Play routine (clock chips until the audio buffer is filled or the player gets paused).
     *
     * @return continue to play next time?
     * @throws InterruptedException audio production interrupted
     */
    private boolean play() throws InterruptedException {
        // Host-time watchdog also runs while paused; the emulated autostart monitor keeps pending commands separate.
        warpControl.poll();
        int bufferSize = config.getAudioSection().getBufferSize();
        for (int i = 0; i < bufferSize; i++) {
            if (stateProperty.get() == PLAY) {
                c64.getEventScheduler().clock();
            }
        }
        if (stateProperty.get() == PAUSE) {
            c64.getEventScheduler().clockThreadSafeEvents();
            Thread.sleep(PAUSE_SLEEP_TIME);
        }
        return stateProperty.get() == PLAY || stateProperty.get() == PAUSE;
    }

    /**
     * Close player.
     */
    private void close() {
        try {
            if (c64.peekInspection() != null) c64.peekInspection().stop();
            warpSupported = false;
            autostartControl.cancel();
            warpControl.setManual(false);
            stateProperty.removeListener(pauseListener);
            c64.insertSIDChips(noSIDs, sidLocator);
            if (getAudioDriver() instanceof VideoDriver) {
                removeVideoDriver((VideoDriver) getAudioDriver());
            }
            if (getAudioDriver() instanceof SIDListener) {
                removeSidListener((SIDListener) getAudioDriver());
            }
            if (getAudioDriver() instanceof IMOS6510Extension) {
                removeMOS6510Extension((IMOS6510Extension) getAudioDriver());
            }
            // save still unwritten sound data
            if (getAudioDriver() != null && getAudioDriver().buffer() != null
                    && (getAudioDriver().isRecording() || stateProperty.get() != QUIT)) {
                try {
                    getAudioDriver().write();
                } catch (SongEndException e) {
                    // ignore natural end
                }
            }
        } catch (Throwable e) {
            if (LOG.isLoggable(Level.FINEST)) {
                LOG.log(Level.FINEST, String.format("Exception near close: fn=%s", getRecordingFilename()), e);
            } else if (LOG.isLoggable(Level.FINE)) {
                LOG.log(Level.FINE, String.format("Exception near close: %s", e.getMessage()));
            }
        } finally {
            if (sidBuilder != null) {
                sidBuilder.destroy();
            }
            if (whatsSidEvent != null) {
                whatsSidEvent.setAbort(true);
            }
            if (getAudioDriver() != null) {
                getAudioDriver().close();
            }
        }
    }

    /**
     * Play tune.
     *
     * @param tune tune to play (RESET means reset C64)
     */
    public final void play(final SidTune tune) {
        play(tune, null);
    }

    /**
     * Reset C64 and enter a basic command.
     *
     * @param command basic command to be entered after a normal reset
     */
    public final void resetC64(String command) {
        play(RESET, command);
    }

    /**
     * Turn C64 off and on, load a tune, and enter a basic command.
     *
     * @param tune    tune to play (RESET means reset C64)
     * @param command basic command to be entered after a normal reset
     */
    private void play(final SidTune tune, final String command) {
        // prevent (re)starting a tune during IniConfigException
        if (stateProperty().get() != OPEN) {
            stopC64();
            setTune(tune);
            setCommand(command);
            startC64();
        }
    }

    /**
     * Pause or continue the player.
     */
    public final void pauseContinue() {
        if (stateProperty.get() == QUIT || stateProperty.get() == END) {
            play(tune);
        } else {
            executeInPlayerThread("PauseContinue", () -> {
                if (stateProperty.get() == PAUSE) {
                    if (c64.peekInspection() != null && c64.peekInspection().isPaused()) {
                        c64.peekInspection().resume();
                    }
                    stateProperty.set(PLAY);
                } else {
                    stateProperty.set(PAUSE);
                }
            });
        }
    }

    /**
     * Play the next song.
     */
    public final void nextSong() {
        executeInPlayerThread("Play next song", () -> {
            playList.next();
            stateProperty.set(RESTART);
        });
    }

    /**
     * Play previous song.<BR>
     * <B>Note:</B> After {@link #PREV_SONG_TIMEOUT} has been reached, the current
     * tune is restarted instead.
     */
    public final void previousSong() {
        executeInPlayerThread("Play previous song", () -> {
            if (time() < PREV_SONG_TIMEOUT) {
                playList.previous();
            }
            stateProperty.set(RESTART);
        });
    }

    /**
     * Play first song.
     */
    public final void firstSong() {
        executeInPlayerThread("Play first song", () -> {
            playList.first();
            stateProperty.set(RESTART);
        });
    }

    /**
     * Play last song.
     */
    public final void lastSong() {
        executeInPlayerThread("Play last song", () -> {
            playList.last();
            stateProperty.set(RESTART);
        });
    }

    /**
     * Get mixer info.
     *
     * @param function     mixer function to apply
     * @param defaultValue default value, if SIDBuilder does not implement a mixer
     * @return mixer info
     */
    public final <T> T getMixerInfo(final Function<Mixer, T> function, final T defaultValue) {
        return sidBuilder instanceof Mixer ? function.apply((Mixer) sidBuilder) : defaultValue;
    }

    /**
     * Quit player.
     */
    public final void quit() {
        executeInPlayerThread("Quit", () -> stateProperty.set(QUIT));
        if (config.getEmulationSection().getUltimate64Mode() != Ultimate64Mode.OFF) {
            sendReset(config, tune);
        }
    }

    /**
     * Set a song length database.
     *
     * @param sidDatabase song length database
     */
    public final void setSidDatabase(final SidDatabase sidDatabase) {
        this.sidDatabase = sidDatabase;
    }

    /**
     * Get song length database info.
     *
     * @param function     SidDatabase function to apply
     * @param <T>          SidDatabase return type
     * @param defaultValue default value, if a database is not set
     * @return song length database info
     */
    public final <T> T getSidDatabaseInfo(final Function<SidDatabase, T> function, final T defaultValue) {
        return sidDatabase != null ? function.apply(sidDatabase) : defaultValue;
    }

    /**
     * Set SID Tune Information List (STIL).
     *
     * @param stil SID Tune Information List
     */
    public final void setSTIL(final STIL stil) {
        this.stil = stil;
    }

    /**
     * Get SID Tune Information List info.
     *
     * @param collectionName entry path to get infos for
     * @return SID Tune Information List info
     */
    public final STILEntry getStilEntry(final String collectionName) {
        return stil != null && collectionName != null ? stil.getSTILEntry(collectionName) : null;
    }

    /**
     * Get the recording filename, add audio related file extension (if known).
     *
     * @return recording filename
     */
    public String getRecordingFilename() {
        AudioDriver audioDriver = getAudioDriver();
        if (audioDriver.getExtension() != null) {
            return recordingFilenameProvider.apply(tune) + audioDriver.getExtension();
        } else {
            return recordingFilenameProvider.apply(tune);
        }
    }

    /**
     * Set the provider of recording filenames.
     *
     * @param recordingFilenameProvider provider of recording filenames
     */
    public final void setRecordingFilenameProvider(final Function<SidTune, String> recordingFilenameProvider) {
        this.recordingFilenameProvider = recordingFilenameProvider;
    }

    /**
     * Add consumer of VIC screen output as ARGB data
     *
     * @param consumer consumer of C64 screen pixels as ARGB data
     */
    public void addVideoDriver(VideoDriver consumer) {
        if (!videoDrivers.contains(consumer)) {
            videoDrivers.add(consumer);
        }
    }

    /**
     * Remove consumer of VIC screen output as ARGB data
     *
     * @param consumer consumer of C64 screen pixels as ARGB data
     */
    public void removeVideoDriver(VideoDriver consumer) {
        videoDrivers.remove(consumer);
    }

    /**
     * Add consumer of SID register writes
     *
     * @param consumer consumer of SID register writes
     */
    public void addSidListener(SIDListener consumer) {
        if (!sidListeners.contains(consumer)) {
            sidListeners.add(consumer);
        }
    }

    /**
     * Remove consumer of SID register writes
     *
     * @param consumer consumer of SID register writes
     */
    public void removeSidListener(SIDListener consumer) {
        sidListeners.remove(consumer);
    }

    /**
     * Add consumer of MOS6510 JMP/JSR instructions.
     *
     * @param mos6510Extension consumer of MOS6510 JMP/JSR instructions
     */
    public void addMOS6510Extension(IMOS6510Extension mos6510Extension) {
        if (!mos6510Extensions.contains(mos6510Extension)) {
            mos6510Extensions.add(mos6510Extension);
        }
    }

    /**
     * Remove consumer of MOS6510 JMP/JSR instructions.
     *
     * @param mos6510Extension of MOS6510 JMP/JSR instructions
     */
    public void removeMOS6510Extension(IMOS6510Extension mos6510Extension) {
        this.mos6510Extensions.remove(mos6510Extension);
    }

    /**
     * Fast-forward skips frames and produces output for each Xth frame (X = 1x, 2x, 4x, ... , 32x).
     */
    @Override
    public void accept(VIC vic) {
        if (isWarp()) {
            long now = warpTime.getAsLong();
            if (nextWarpFrameNanos != 0 && now - nextWarpFrameNanos < 0) {
                return;
            }
            nextWarpFrameNanos = now + 100_000_000L; // 10 presentations per host second.
        } else {
            int fastForwardBitMask = getMixerInfo(Mixer::getFastForwardBitMask, 0);
            if ((fastForwardVICFrames++ & fastForwardBitMask) != fastForwardBitMask) {
                return;
            }
        }
        for (VideoDriver videoDriver : videoDrivers) {
            videoDriver.accept(vic);
        }
    }

    @Override
    public void write(int sidNum, int addr, byte data) {
        for (SIDListener sidListener : sidListeners) {
            sidListener.write(sidNum, addr, data);
        }
    }

    @Override
    public void jmpJsr() {
        for (IMOS6510Extension mos6510Extension : mos6510Extensions) {
            mos6510Extension.jmpJsr();
        }
    }

    public Autodetection getAutodetection() {
        return autodetection;
    }

    /**
     * The credits for the authors of many parts of this emulator.
     *
     * @param version containing the version of JSIDPlay2
     * @return the credits
     */
    public final String getCredits(final String version) {
        final StringBuilder credits = new StringBuilder();
        credits.append("Operating System:\n");
        credits.append(OS.get()).append("\n");
        credits.append("\nJava version:\n");
        credits.append(System.getProperty("java.runtime.version"));
        credits.append("\n").append(System.getProperty("sun.arch.data.model")).append(" bits");
        credits.append("\n\nJava Version and User Interface v");
        credits.append(version);
        credits.append(":\n");
        credits.append("\tCopyright (©) 2007-").append(LAST_MODIFIED.get(Calendar.YEAR)).append(" Ken Händel\n");
        credits.append("\thttp://sourceforge.net/projects/jsidplay2/\n");
        credits.append("Distortion Simulation and development: Antti S. Lankila\n");
        credits.append("\thttp://bel.fi/~alankila/c64-sw/\n");
        credits.append("Testing and Feedback: Nata, founder of proNoise\n");
        credits.append("\thttp://www.nata.netau.net/\n");
        credits.append("OpenAI Codex:\n");
        credits.append("\tAI assistance with SID/FM-OPL oscilloscope design, implementation,\n");
        credits.append("\tperformance analysis, and testing.\n");
        credits.append("Media tests and preservation research:\n");
        credits.append("\tVICE Team and test-program authors - test corpus and independent emulator comparisons.\n");
        credits.append("\tBanGuiBob - RapidLok 6 Handbook, disassemblies and Pirates! captures.\n");
        credits.append("\tPete Rittwage, Markus Brenner and NIBTools contributors - NIB/NBZ/NB2 format evidence.\n");
        credits.append("\tMarcus Geelnard - LZ77 reference codec for NBZ interoperability.\n");
        credits.append("\tC64 Preservation Project contributors - preserved original disk captures.\n");
        credits.append("\tLordCrass - Revolution-V and V-MAX! analysis; Marty Franz - original V-MAX! sources.\n");
        credits.append("\tDaryl Krans - ReMaster Utility's Vorpal and RapidLok format analysis.\n");
        credits.append("\tBenjamin \"BeRo\" Rosseaux - micro64 Disk Tool comparison sources.\n");
        credits.append("\tPeter Schepers and contributors - D64/G64 format documentation.\n");
        credits.append("\tScott Nelson/Epyx and MicroProse - original game and loader code.\n");
        credits.append("\tKryoFlux - authorized original-disk examples for optional local tests.\n");
        credits.append("\tDetailed acknowledgements, source references and original notices:\n");
        credits.append("\thttps://sourceforge.net/p/jsidplay2/git/ci/master/tree/src/test/resources/external-c64/README.md\n");
        credits.append("Source code originally based on libsidplay v2.1.1 and ReSID v0.0.2 engine:\n");
        credits.append("\tCopyright (©) 1999-2002 Simon White <sidplay2@yahoo.com>\n");
        credits.append("\thttp://sidplay2.sourceforge.net\n");
        credits.append("SIDv4E (proprietary SID file format+ used for multi-SID tunes)\n");
        credits.append("\tCopyright (©) 2019 Jürgen Wothke\n");
        credits.append("Icon used from Wikimedia\n");
        credits.append("\tCreative Commons License Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)\n");
        credits.append("\thttps://creativecommons.org/licenses/by-sa/3.0/legalcode\n");
        credits.append("Network SID Device:\n");
        credits.append("\tCopyright (©) 2011 Antti S. Lankila <alankila@bel.fi>\n");
        credits.append("\tSupported by Wilfred Bos, The Netherlands\n");
        credits.append("\thttp://www.acid64.com\n");
        credits.append("WhatsSID? (tune recognition)\n");
        credits.append("\tCopyright (©) 2020 Ken Händel\n");
        credits.append("Based on Audio Fingerprinting\n");
        credits.append("\tCopyright (©) 2015-2019 J. Pery\n");
        credits.append("\thttps://github.com/JPery/Audio-Fingerprinting\n");
        credits.append("Forked from Audio-Fingerprinting:\n");
        credits.append("\tCopyright (©) 2015 hsyecheng <hsyecheng@hotmail.com>\n");
        credits.append("\thttps://github.com/hsyecheng/Audio-Fingerprinting\n");
        credits.append("jump3r (MP3 encoder/decoder)\n");
        credits.append("\tCopyright (©) 2010-2011 Ken Händel\n");
        credits.append("\thttp://sourceforge.net/projects/jsidplay2/\n");
        credits.append("Based on Lame (Lame Aint an MP3 Encoder v3.98.4)\n");
        credits.append("\thttps://sourceforge.net/projects/lame/\n");
        credits.append("Assembly64:\n");
        credits.append("\tCopyright (©) ").append(LAST_MODIFIED.get(Calendar.YEAR)).append(" Fredrik Åberg\n");
        credits.append("\thttps://hackerswithstyle.se/assembly/\n");
        credits.append("GB64 (We use the database of Game Base 64)\n");
        credits.append("\thttp://www.gb64.com/\n");
        credits.append("JCommander (Command Line Parser):\n");
        credits.append("\tCopyright (©) 2010-2014 Cédric Beust\n");
        credits.append("\thttp://jcommander.org/\n");
        credits.append("Xuggler (Audio/Video Encoder):\n");
        credits.append("\tCopyright (©) 2011 and All Rights Reserved by ConnectSolutions, LLC.\n");
        credits.append("\thttp://www.xuggle.com/xuggler/\n");
        credits.append("MP3 downloads from Stone Oakvalley's Authentic SID MusicCollection (SOASC=):\n");
        credits.append("\thttp://www.6581-8580.com/\n");
        credits.append("Kickassembler (6510 cross assembler):\n");
        credits.append("\tCopyright (©) 2006-").append(LAST_MODIFIED.get(Calendar.YEAR)).append(" Mads Nielsen\n");
        credits.append("\thttp://www.theweb.dk/KickAssembler/\n");
        credits.append("PSID64 (PSID to PRG converter v0.9):\n");
        credits.append("\tCopyright (©) 2001-2007 Roland Hermans\n");
        credits.append("\thttp://sourceforge.net/projects/psid64/\n");
        credits.append("Pucrunch (An Optimizing Hybrid LZ77 RLE Data Compression Program):\n");
        credits.append("\tCopyright (©) 1997-2008 Pasi 'Albert' Ojala\n");
        credits.append("\thttp://www.cs.tut.fi/~albert/Dev/pucrunch/\n");
        credits.append("SIDDump (SID dump file v1.04):\n");
        credits.append("\tCopyright (©) 2007 Lasse Öörni\n");
        credits.append("SIDId (HVSC playroutine identity scanner v1.07):\n");
        credits.append("\tCopyright (©) 2007 Lasse Öörni\n");
        credits.append("HVMEC (High Voltage Music Engine Collection v1.0):\n");
        credits.append("\tCopyright (©) 2011 by Stefano Tognon and Stephan Parth\n");
        credits.append("FMOPL (FM sound generator types OPL and OPL2 v0.72):\n");
        credits.append("\tJava version by Daniel Becker Copyright (©) 2020\n");
        credits.append("Based on MAME (multi-purpose emulation framework)\n");
        credits.append("\tCopyright (©) 2020 by Jarek Burczynski and Tatsuyuki Satoh\n");
        credits.append("\thttps://www.mamedev.org/\n");
        credits.append("C1541 Floppy Disk Drive Emulation:\n");
        credits.append("\tCopyright (©) 2010 VICE (the Versatile Commodore Emulator)\n");
        credits.append("\thttp://www.viceteam.org/\n");
        credits.append("JiffyDOS ROMs:\n");
        credits.append("\tCopyright (©) by CMD Software\n");
        credits.append("\thttp://cmdweb.com\n");
        credits.append("\tLicense can be obtained at https://restore-store.de\n");
        credits.append(MOS6510.credits());
        credits.append(MOS6526.credits());
        credits.append(VIC.credits());
        credits.append(builder.resid.resid.ReSID.credits());
        credits.append(builder.resid.residfp.ReSIDfp.credits());
        credits.append(builder.resid.residfp.circuit.ReSIDfpCircuit.credits());
        credits.append(SIDBuilderFactory.credits());
        return credits.toString();
    }

    /**
     * Play one tune using software SID emulation and JavaSound.
     *
     * @param args filename, optional song number and optional fallback duration in seconds
     * @throws SidTuneError SID tune error
     * @throws IOException tune file cannot be read
     * @throws InterruptedException playback interrupted
     */
    public static void main(final String[] args) throws IOException, SidTuneError, InterruptedException {
        final String usage = """
                Usage: java -jar libsidplay.jar <filename> [song] [default-seconds]
                Plays one song with JavaSound. The tune's start song is used by default.
                default-seconds is the fallback duration when no song length is known (default: 0, unlimited).
                Press Ctrl+C to stop playback.
                """;
        if (args.length == 1 && ("--help".equals(args[0]) || "-h".equals(args[0]))) {
            System.out.print(usage);
            return;
        }
        if (args.length < 1 || args.length > 3) {
            System.err.print(usage);
            System.exit(2);
            return;
        }
        final SidTune tune = SidTune.load(new File(args[0]));
        if (args.length > 1) {
            int song = Integer.parseInt(args[1]);
            if (song < 1 || song > tune.getInfo().getSongs()) {
                throw new IllegalArgumentException("Song must be between 1 and " + tune.getInfo().getSongs());
            }
            tune.getInfo().setSelectedSong(song);
        }
        final IniConfig config = new IniConfig();
        config.getEmulationSection().setEngine(Engine.EMULATION);
        config.getAudioSection().setAudio(Audio.SOUNDCARD);
        config.getSidplay2Section().setSingle(true);
        config.getSidplay2Section().setLoop(false);
        config.getWhatsSidSection().setEnable(false);
        if (args.length > 2) {
            double seconds = Double.parseDouble(args[2]);
            if (!Double.isFinite(seconds) || seconds < 0) {
                throw new IllegalArgumentException("Default duration must be a finite, non-negative number of seconds");
            }
            config.getSidplay2Section().setDefaultPlayLength(seconds);
        }
        final Player player = new Player(config);
        final AtomicReference<Throwable> failure = new AtomicReference<>();
        player.setUncaughtExceptionHandler((thread, error) -> failure.set(error));
        final Thread shutdownHook = new Thread(player::stopC64, "Player shutdown");
        Runtime.getRuntime().addShutdownHook(shutdownHook);
        try {
            player.play(tune);
            player.playerThread.join();
        } finally {
            player.stopC64();
            try {
                Runtime.getRuntime().removeShutdownHook(shutdownHook);
            } catch (IllegalStateException e) {
                // The shutdown hook is already stopping the player.
            }
        }
        if (failure.get() != null) {
            throw new IllegalStateException("Playback failed: " + failure.get().getMessage(), failure.get());
        }
    }

}