lockstep-player/app/src/main/java/at/lockstep/player/pasada/LibPasada.java

package at.lockstep.player.pasada;

/**
 * JNI entry point for libpasada. Used by {@link at.lockstep.player.playback.engine.PasadaMusicPlayerEngine};
 * {@link at.lockstep.player.playback.PlaybackService} still defaults to
 * {@link at.lockstep.player.playback.engine.ExoPlayerMusicPlayerEngine} until the native library is ready.
 *
 * <p>Native state machine: LOADED → INITIALIZED → PLAYING ↔ PAUSED → FINISHED → STOPPED
 *
 * <p>Call {@link #loadNative()} once before any other method once the {@code pasada} shared
 * library is added via CMake (step 3).
 */
public final class LibPasada {

    private static boolean loaded;

    private LibPasada() {}

    /** Loads {@code libpasada.so}. Safe to call multiple times. */
    public static synchronized void loadNative() {
        if (loaded) {
            return;
        }
        System.loadLibrary("lockstep-native");
        loaded = true;
    }

    /** Called each time a run/playlist session starts (Oboe silent, buffers ready). */
    public static native void init();

    /** Submit one accelerometer sample (m/s²); may be called from a sensor thread. */
    public static native void feedAccel(float x, float y, float z, long timestampNanos);

    /**
     * Open MP3 from an already-open file descriptor and begin adaptive playback.
     *
     * @param fd open read FD (Java retains ownership; do not close until track changes)
     * @param offset start offset within the FD (0 for whole file)
     * @param length byte length from offset ({@code -1} if unknown / to EOF)
     */
    public static native void play(int fd, long offset, long length);

    /** PLAYING → PAUSED (silent output, graph kept alive). */
    public static native void pause();

    /** PAUSED → PLAYING (same track, same decode position, same FD). */
    public static native void resume();

    /** Tear down Oboe for this run segment → STOPPED. */
    public static native void stop();

    /**
     * Milliseconds from the start of the current track — same timebase as ExoPlayer
     * {@code getCurrentPosition()}. Safe to poll from background threads.
     */
    public static native long getCurrentPositionMs();

    /** Track duration in ms, or {@code 0} if not yet known. */
    public static native long getDurationMs();

    /** Whether adapted audio is actively being output (not paused, not finished). */
    public static native boolean isPlaying();

    /** Current native state; see {@link PasadaState}. */
    public static native int getState();

    /** Seek within the current track. */
    public static native void seekTo(long positionMs);

    /** Runtime metrics / last error string for logging and debug UI. */
    public static native String getDiagnostics();

    /** Register listener for async events raised from the audio/native thread. */
    public static native void setPlaybackListener(PasadaPlaybackListener listener);

    /** native version string */
    public static native String getVersion();
}