hookjump 0.1.0__py3-none-any.whl

hookjump/__init__.py

@@ -0,0 +1,12 @@
+"""hookjump: jump to the best part of the song that is playing.
+
+The best part comes from repeated lines in time-synced lyrics (the chorus) and,
+over time, from the listener's own rewinds and replays, recorded locally.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("hookjump")
+except PackageNotFoundError:  # running from a source tree without installing
+    __version__ = "0+unknown"

hookjump/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m hookjump``: the same as the ``hookjump`` command."""
+
+import sys
+
+from hookjump.cli import main
+
+sys.exit(main())

hookjump/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Adapters: the code between the core and the world (disk, player, network).
+
+The core computes; adapters store, read the player and fetch. The storage
+format is written down in spec/STORAGE.md so other platforms can share it.
+"""

hookjump/adapters/carbon_hotkeys.py

@@ -0,0 +1,113 @@
+"""Door 1: global hotkeys through Carbon's RegisterEventHotKey, via ctypes.
+
+Every shortcut manager on macOS uses this call. It needs no permission (an
+event monitor would need Accessibility), and it takes the key: the app in
+front does not also get it. Carbon is old, so this is the only part that
+depends on it, and door 2 (the ``hookjump jump`` command) works without it.
+
+The callbacks run on the main thread, while the app's run loop is running.
+"""
+
+import ctypes
+import ctypes.util
+from collections.abc import Callable
+
+from hookjump.shortcut import Shortcut
+
+
+def _code(text: str) -> int:
+    return int.from_bytes(text.encode("latin-1"), "big")
+
+
+class _HotKeyID(ctypes.Structure):
+    _fields_ = [("signature", ctypes.c_uint32), ("id", ctypes.c_uint32)]
+
+
+class _EventTypeSpec(ctypes.Structure):
+    _fields_ = [("eventClass", ctypes.c_uint32), ("eventKind", ctypes.c_uint32)]
+
+
+_HANDLER = ctypes.CFUNCTYPE(
+    ctypes.c_int32, ctypes.c_void_p, ctypes.c_void_p, ctypes.c_void_p
+)
+_SIGNATURE = _code("hkjp")
+_HOT_KEY_PRESSED = 5  # kEventHotKeyPressed
+_NOT_HANDLED = -9874  # eventNotHandledErr
+
+
+class HotkeyError(RuntimeError):
+    """macOS refused a shortcut (15.0 and 15.1 refuse ones with ⌥ alone).
+
+    A shortcut another app has registered is not refused: macOS lets two apps
+    register the same one, so such a clash cannot be found out here.
+    """
+
+
+class CarbonHotkeys:
+    def __init__(self) -> None:
+        self._carbon = ctypes.cdll.LoadLibrary(ctypes.util.find_library("Carbon"))
+        c = self._carbon
+        c.GetApplicationEventTarget.restype = ctypes.c_void_p
+        c.InstallEventHandler.argtypes = [
+            ctypes.c_void_p, _HANDLER, ctypes.c_ulong,
+            ctypes.POINTER(_EventTypeSpec), ctypes.c_void_p,
+            ctypes.POINTER(ctypes.c_void_p),
+        ]  # fmt: skip
+        c.RegisterEventHotKey.argtypes = [
+            ctypes.c_uint32, ctypes.c_uint32, _HotKeyID, ctypes.c_void_p,
+            ctypes.c_uint32, ctypes.POINTER(ctypes.c_void_p),
+        ]  # fmt: skip
+        c.UnregisterEventHotKey.argtypes = [ctypes.c_void_p]
+        c.GetEventParameter.argtypes = [
+            ctypes.c_void_p, ctypes.c_uint32, ctypes.c_uint32, ctypes.c_void_p,
+            ctypes.c_ulong, ctypes.c_void_p, ctypes.c_void_p,
+        ]  # fmt: skip
+
+        self._actions: dict[int, Callable[[], None]] = {}
+        self._refs: dict[int, ctypes.c_void_p] = {}
+        # Keep the C callback alive as long as this object: if Python freed it,
+        # the next key press would call freed memory and crash the app.
+        self._callback = _HANDLER(self._on_event)
+        spec = _EventTypeSpec(_code("keyb"), _HOT_KEY_PRESSED)
+        status = c.InstallEventHandler(
+            c.GetApplicationEventTarget(), self._callback, 1, ctypes.byref(spec),
+            None, ctypes.byref(ctypes.c_void_p()),
+        )  # fmt: skip
+        if status != 0:
+            raise HotkeyError(f"could not listen for hotkeys (error {status})")
+
+    def bind(self, shortcut: Shortcut, action: Callable[[], None]) -> None:
+        number = len(self._actions) + 1
+        ref = ctypes.c_void_p()
+        status = self._carbon.RegisterEventHotKey(
+            shortcut.key_code, shortcut.modifiers, _HotKeyID(_SIGNATURE, number),
+            self._carbon.GetApplicationEventTarget(), 0, ctypes.byref(ref),
+        )  # fmt: skip
+        if status != 0:
+            raise HotkeyError(f"{shortcut} could not be registered (error {status})")
+        self._actions[number] = action
+        self._refs[number] = ref
+
+    def unbind_all(self) -> None:
+        for ref in self._refs.values():
+            self._carbon.UnregisterEventHotKey(ref)
+        self._refs.clear()
+        self._actions.clear()
+
+    def _on_event(self, _call: object, event: object, _data: object) -> int:
+        # Never let an exception cross into C: report it and carry on.
+        try:
+            hot_key = _HotKeyID()
+            self._carbon.GetEventParameter(
+                event, _code("----"), _code("hkid"), None,
+                ctypes.sizeof(hot_key), None, ctypes.byref(hot_key),
+            )  # fmt: skip
+            action = self._actions.get(hot_key.id)
+            if hot_key.signature != _SIGNATURE or action is None:
+                return _NOT_HANDLED
+            action()
+        except Exception:  # noqa: BLE001
+            import traceback
+
+            traceback.print_exc()
+        return 0

hookjump/adapters/keyboard.py

@@ -0,0 +1,65 @@
+"""What a key combination types on the listener's keyboard layout right now.
+
+A shortcut recorder needs it: on a Turkish Q keyboard ⌥Q types "@", and taking
+⌥Q as a hotkey would leave the listener unable to type "@". Asked of macOS
+(UCKeyTranslate), so it is right for any layout, not a table we keep.
+
+Known limit: a letter typed with ⌥ counts as rare, like ⌥F's "ƒ". On layouts
+that type their own letters with ⌥ (Polish Pro: ⌥A is "ą"), such a shortcut
+would still be accepted and take that letter away.
+"""
+
+import ctypes
+import ctypes.util
+
+from hookjump.shortcut import Shortcut
+
+_SHIFT_OPTION = 0x0200 | 0x0800  # the only modifiers that change typed text
+_COMMAND_CONTROL = 0x0100 | 0x1000
+_KEY_DOWN = 0  # kUCKeyActionDown
+
+
+def typed_by(shortcut: Shortcut) -> tuple[str | None, bool]:
+    """(the text it types, or None; whether it starts an accent instead)."""
+    if shortcut.modifiers & _COMMAND_CONTROL:
+        return None, False  # ⌘ and ⌃ combinations type nothing
+    carbon = ctypes.cdll.LoadLibrary(ctypes.util.find_library("Carbon"))
+    foundation = ctypes.cdll.LoadLibrary(ctypes.util.find_library("CoreFoundation"))
+    carbon.TISCopyCurrentKeyboardLayoutInputSource.restype = ctypes.c_void_p
+    carbon.TISGetInputSourceProperty.restype = ctypes.c_void_p
+    carbon.TISGetInputSourceProperty.argtypes = [ctypes.c_void_p, ctypes.c_void_p]
+    carbon.LMGetKbdType.restype = ctypes.c_uint8
+    foundation.CFDataGetBytePtr.restype = ctypes.c_void_p
+    foundation.CFDataGetBytePtr.argtypes = [ctypes.c_void_p]
+    foundation.CFRelease.argtypes = [ctypes.c_void_p]
+
+    source = carbon.TISCopyCurrentKeyboardLayoutInputSource()
+    try:
+        key = ctypes.c_void_p.in_dll(carbon, "kTISPropertyUnicodeKeyLayoutData")
+        data = carbon.TISGetInputSourceProperty(source, key)
+        if not data:
+            return None, False  # an input method without a key layout
+        layout = foundation.CFDataGetBytePtr(data)
+        dead, length, chars = (
+            ctypes.c_uint32(0),
+            ctypes.c_ulong(0),
+            (ctypes.c_uint16 * 4)(),
+        )
+        carbon.UCKeyTranslate(
+            ctypes.c_void_p(layout),
+            ctypes.c_uint16(shortcut.key_code),
+            ctypes.c_uint16(_KEY_DOWN),
+            ctypes.c_uint32((shortcut.modifiers & _SHIFT_OPTION) >> 8),
+            ctypes.c_uint32(carbon.LMGetKbdType()),
+            ctypes.c_uint32(0),  # dead keys on: an accent key reports itself
+            ctypes.byref(dead),
+            ctypes.c_ulong(len(chars)),
+            ctypes.byref(length),
+            chars,
+        )
+    finally:
+        foundation.CFRelease(source)
+    if length.value == 0 and dead.value:
+        return None, True
+    text = "".join(chr(chars[i]) for i in range(length.value))
+    return text or None, False

hookjump/adapters/spotify.py

@@ -0,0 +1,167 @@
+"""The Spotify turntable for macOS: Apple events, run in-process with PyObjC.
+
+Spotify answers one property per Apple event, at about 17 ms each, so a poll
+asks only what changes every second: the track id, then the app's properties
+record (state and position in a single event). Title, artist and duration are
+asked only when the track changes. Measured on macOS 26 with Spotify 1.3.
+
+The id and the properties come from two events, a few milliseconds apart. If
+the track changes in between, the reading pairs the old id with the new
+track's position, which is near 0; seek detection takes that for a restart and
+ignores it. That is why the id is read first.
+"""
+
+import math
+
+from AppKit import NSWorkspace
+from Foundation import NSAppleScript
+
+from hookjump.adapters.turntable import Reading
+
+BUNDLE_ID = "com.spotify.client"
+_TIMEOUT_S = 2  # a hung Spotify must not freeze polling (the default is 2 min)
+
+_POLL = f"""
+if application id "{BUNDLE_ID}" is not running then return "not running"
+tell application id "{BUNDLE_ID}"
+    with timeout of {_TIMEOUT_S} seconds
+        try
+            set trackId to id of current track
+        on error
+            set trackId to missing value
+        end try
+        set p to properties
+        return {{trackId, (player state of p) as text, player position of p}}
+    end timeout
+end tell
+"""
+_TRACK = f"""
+tell application id "{BUNDLE_ID}"
+    with timeout of {_TIMEOUT_S} seconds
+        set t to current track
+        return {{id of t, name of t, artist of t, duration of t}}
+    end timeout
+end tell
+"""
+_PLACE = """
+if application id "{bundle}" is not running then return false
+tell application id "{bundle}"
+    with timeout of {timeout} seconds
+        if player state is stopped then return false
+        if (id of current track) is not "{track}" then return false
+        set player position to {seconds}
+    end timeout
+end tell
+return true
+"""
+
+# Apple event error numbers.
+_NOT_PERMITTED = -1743  # the listener has not allowed hookjump to control Spotify
+_GONE = {-600, -609, -1712}  # quit, connection lost, timed out
+
+
+def _code(text: str) -> int:
+    return int.from_bytes(text.encode("latin-1"), "big")
+
+
+_TYPE, _MISSING = _code("type"), _code("msng")
+
+
+class SpotifyNotInstalled(RuntimeError):
+    pass
+
+
+class Spotify:
+    """A turntable for the Spotify desktop app (hookjump.adapters.turntable)."""
+
+    name = "Spotify"
+
+    def __init__(self) -> None:
+        # Compiling a script for an app that is not installed can open a
+        # "Where is Spotify?" dialog; check first.
+        workspace = NSWorkspace.sharedWorkspace()
+        if workspace.URLForApplicationWithBundleIdentifier_(BUNDLE_ID) is None:
+            raise SpotifyNotInstalled("Spotify is not installed")
+        self._poll = _compile(_POLL)
+        self._track = _compile(_TRACK)
+        self._known: tuple[str, str | None, str | None, int | None] | None = None
+
+    def read(self) -> Reading | None:
+        result = _run(self._poll)
+        if result is None or result.stringValue() == "not running":
+            return None
+        track_id = _text(result.descriptorAtIndex_(1))
+        playing = _text(result.descriptorAtIndex_(2)) == "playing"
+        position = _seconds_to_ms(result.descriptorAtIndex_(3))
+        if track_id is None or track_id.startswith("spotify:ad:"):
+            # Nothing loaded, or an ad: no track to learn from or jump in.
+            return Reading(None, None, None, None, playing, None)
+        title, artist, duration = self._details(track_id)
+        return Reading(track_id, title, artist, duration, playing, position)
+
+    def place(self, track_id: str, position_ms: int) -> bool:
+        source = _PLACE.format(
+            bundle=BUNDLE_ID,
+            timeout=_TIMEOUT_S,
+            track=track_id.replace("\\", "\\\\").replace('"', '\\"'),
+            seconds=f"{position_ms / 1000:.3f}",  # always a "." in source
+        )
+        result = _run(_compile(source))
+        return result is not None and result.booleanValue()
+
+    def _details(self, track_id: str) -> tuple[str | None, str | None, int | None]:
+        if self._known is None or self._known[0] != track_id:
+            result = _run(self._track)
+            if result is None or _text(result.descriptorAtIndex_(1)) != track_id:
+                return None, None, None  # changed again meanwhile: next poll
+            duration = result.descriptorAtIndex_(4)
+            self._known = (
+                track_id,
+                _text(result.descriptorAtIndex_(2)),
+                _text(result.descriptorAtIndex_(3)),
+                # Spotify's dictionary says seconds; it returns milliseconds.
+                None if _missing(duration) else round(duration.doubleValue()),
+            )
+        return self._known[1:]
+
+
+def _compile(source: str) -> NSAppleScript:
+    script = NSAppleScript.alloc().initWithSource_(source)
+    ok, error = script.compileAndReturnError_(None)
+    if not ok:
+        raise RuntimeError(f"AppleScript did not compile: {dict(error)}")
+    return script
+
+
+def _run(script: NSAppleScript):  # -> NSAppleEventDescriptor | None
+    """Run a script; None if Spotify is gone or did not answer in time."""
+    result, error = script.executeAndReturnError_(None)
+    if error is None:
+        return result
+    number = int(error.get("NSAppleScriptErrorNumber", 0))
+    if number == _NOT_PERMITTED:
+        raise PermissionError(
+            "hookjump may not control Spotify. Allow it in System Settings >"
+            " Privacy & Security > Automation."
+        )
+    if number in _GONE:
+        return None
+    raise RuntimeError(
+        f"Spotify did not answer: {error.get('NSAppleScriptErrorMessage')}"
+    )
+
+
+def _missing(descriptor) -> bool:
+    return descriptor is None or (
+        descriptor.descriptorType() == _TYPE and descriptor.typeCodeValue() == _MISSING
+    )
+
+
+def _text(descriptor) -> str | None:
+    return None if _missing(descriptor) else descriptor.stringValue()
+
+
+def _seconds_to_ms(descriptor) -> int | None:
+    if _missing(descriptor):
+        return None
+    return math.floor(descriptor.doubleValue() * 1000 + 0.5)  # ALGORITHM.md §1

hookjump/adapters/storage.py

@@ -0,0 +1,276 @@
+"""Local SQLite storage for what hookjump learns (spec/STORAGE.md).
+
+Raw samples are kept for 7 days; the seeks found in them and the listener's
+pins are kept for good. The kept tables hold no dates or times.
+"""
+
+import os
+import sqlite3
+from pathlib import Path
+
+from hookjump.core.heatmap import RECENT_LISTENS
+from hookjump.core.models import Pin, PlaybackSample, SeekEvent
+from hookjump.core.seek import detect
+
+SCHEMA_VERSION = 1
+SAMPLE_DAYS = 7
+_DAY_MS = 24 * 60 * 60 * 1000
+
+_SCHEMA = """
+CREATE TABLE pins (
+    track_id TEXT PRIMARY KEY,
+    at_ms INTEGER NOT NULL CHECK (at_ms >= 0),
+    typed INTEGER NOT NULL CHECK (typed IN (0, 1))
+);
+CREATE TABLE seeks (
+    track_id TEXT NOT NULL,
+    listen INTEGER NOT NULL,
+    from_ms INTEGER NOT NULL,
+    to_ms INTEGER NOT NULL
+);
+CREATE INDEX seeks_by_track ON seeks (track_id, listen);
+CREATE TABLE samples (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    at_ms INTEGER NOT NULL,
+    track_id TEXT,
+    playing INTEGER NOT NULL,
+    position_ms INTEGER,
+    own_seek INTEGER NOT NULL
+);
+CREATE TABLE ignored (
+    track_id TEXT PRIMARY KEY
+);
+CREATE TABLE settings (
+    key TEXT PRIMARY KEY,
+    value INTEGER NOT NULL
+);
+"""
+
+
+def default_path() -> Path:
+    """Application Support, or the HOOKJUMP_DB variable (for trying things out)."""
+    if path := os.environ.get("HOOKJUMP_DB"):
+        return Path(path)
+    return Path.home() / "Library" / "Application Support" / "hookjump" / "hookjump.db"
+
+
+class Store:
+    """One hookjump database. Use as a context manager, or call close()."""
+
+    def __init__(self, path: Path | str) -> None:
+        if path != ":memory:":
+            Path(path).parent.mkdir(parents=True, exist_ok=True)
+        self._db = sqlite3.connect(path)
+        # Deleted rows are overwritten, not left readable in free pages.
+        self._db.execute("PRAGMA secure_delete = ON")
+        version = self._db.execute("PRAGMA user_version").fetchone()[0]
+        if version == 0:
+            with self._db:
+                self._db.executescript(_SCHEMA)
+                self._db.execute(f"PRAGMA user_version = {SCHEMA_VERSION}")
+        elif version != SCHEMA_VERSION:
+            self._db.close()
+            raise RuntimeError(
+                f"{path} has schema version {version}; this hookjump reads"
+                f" version {SCHEMA_VERSION}"
+            )
+
+    def close(self) -> None:
+        self._db.close()
+
+    def __enter__(self) -> "Store":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # Samples and seeks ------------------------------------------------------
+
+    def add_sample(self, sample: PlaybackSample) -> int | None:
+        """Record one poll; its ``at_ms`` is Unix time in milliseconds.
+
+        Nothing is written while learning is paused or for an ignored track.
+        Returns the sample's id, or None if it was not written.
+        """
+        if self.learning_paused() or (
+            sample.track_id is not None and self.is_ignored(sample.track_id)
+        ):
+            return None
+        with self._db:
+            cursor = self._db.execute(
+                "INSERT INTO samples (at_ms, track_id, playing, position_ms,"
+                " own_seek) VALUES (?, ?, ?, ?, ?)",
+                (
+                    sample.at_ms,
+                    sample.track_id,
+                    int(sample.playing),
+                    sample.position_ms,
+                    int(sample.own_seek),
+                ),
+            )
+        return cursor.lastrowid
+
+    def process(self, before_id: int | None = None) -> int:
+        """Find the seeks in the samples not processed yet and keep them.
+
+        Pass the id of the first sample of the listen still going on, so a
+        listen is never cut in two (it would count as two listens); pass None
+        when nothing is playing any more, such as at start-up. Returns the
+        number of seeks kept.
+        """
+        done = self._setting("processed_sample_id")
+        rows = self._db.execute(
+            "SELECT id, at_ms, track_id, playing, position_ms, own_seek"
+            " FROM samples WHERE id > ? AND (? IS NULL OR id < ?) ORDER BY id",
+            (done, before_id, before_id),
+        ).fetchall()
+        if not rows:
+            return 0
+        samples = [
+            PlaybackSample(at, track, bool(playing), position, bool(own))
+            for _, at, track, playing, position, own in rows
+        ]
+        seeks = [e for e in detect(samples) if isinstance(e, SeekEvent)]
+
+        # detect() numbers listens within this batch. Kept listen numbers count
+        # per track, only for listens with seeks, and only ever grow. Each seek
+        # is inserted at once, so the next listen of the track counts on from it.
+        numbers: dict[tuple[str, int], int] = {}
+        with self._db:
+            for seek in seeks:
+                key = (seek.track_id, seek.listen)
+                if key not in numbers:
+                    numbers[key] = self._last_listen(seek.track_id) + 1
+                self._db.execute(
+                    "INSERT INTO seeks (track_id, listen, from_ms, to_ms)"
+                    " VALUES (?, ?, ?, ?)",
+                    (seek.track_id, numbers[key], seek.from_ms, seek.to_ms),
+                )
+            for track_id in {s.track_id for s in seeks}:
+                self._keep_recent(track_id)
+            self._set_setting("processed_sample_id", rows[-1][0])
+        return len(seeks)
+
+    def seeks(self, track_id: str) -> list[SeekEvent]:
+        rows = self._db.execute(
+            "SELECT listen, from_ms, to_ms FROM seeks WHERE track_id = ?"
+            " ORDER BY listen, rowid",
+            (track_id,),
+        ).fetchall()
+        return [SeekEvent(track_id, *row) for row in rows]
+
+    def purge_samples(self, now_ms: int) -> int:
+        """Delete processed samples older than SAMPLE_DAYS; returns how many."""
+        with self._db:
+            cursor = self._db.execute(
+                "DELETE FROM samples WHERE at_ms < ? AND id <= ?",
+                (now_ms - SAMPLE_DAYS * _DAY_MS, self._setting("processed_sample_id")),
+            )
+        return cursor.rowcount
+
+    # Pins -------------------------------------------------------------------
+
+    def pin(self, track_id: str) -> Pin | None:
+        row = self._db.execute(
+            "SELECT at_ms, typed FROM pins WHERE track_id = ?", (track_id,)
+        ).fetchone()
+        return Pin(row[0], bool(row[1])) if row else None
+
+    def set_pin(self, track_id: str, pin: Pin) -> None:
+        with self._db:
+            self._db.execute(
+                "INSERT OR REPLACE INTO pins (track_id, at_ms, typed) VALUES (?, ?, ?)",
+                (track_id, pin.at_ms, int(pin.typed)),
+            )
+
+    def clear_pin(self, track_id: str) -> None:
+        with self._db:
+            self._db.execute("DELETE FROM pins WHERE track_id = ?", (track_id,))
+
+    # Settings ---------------------------------------------------------------
+
+    def shortcut(self, name: str) -> int:
+        """A stored shortcut (``Shortcut.to_int``) or 0 for the default."""
+        return self._setting(f"{name}_shortcut")
+
+    def set_shortcut(self, name: str, value: int) -> None:
+        with self._db:
+            self._set_setting(f"{name}_shortcut", value)
+
+    # Privacy ----------------------------------------------------------------
+
+    def learning_paused(self) -> bool:
+        return bool(self._setting("learning_paused"))
+
+    def set_learning_paused(self, paused: bool) -> None:
+        with self._db:
+            self._set_setting("learning_paused", int(paused))
+
+    def is_ignored(self, track_id: str) -> bool:
+        row = self._db.execute(
+            "SELECT 1 FROM ignored WHERE track_id = ?", (track_id,)
+        ).fetchone()
+        return row is not None
+
+    def ignore(self, track_id: str) -> None:
+        """Stop learning from a track and forget what was learned. Pins stay."""
+        with self._db:
+            self._db.execute(
+                "INSERT OR IGNORE INTO ignored (track_id) VALUES (?)", (track_id,)
+            )
+            self._forget_learned(track_id)
+
+    def unignore(self, track_id: str) -> None:
+        with self._db:
+            self._db.execute("DELETE FROM ignored WHERE track_id = ?", (track_id,))
+
+    def forget_track(self, track_id: str) -> None:
+        """Forget one track: its pin and everything learned from it."""
+        with self._db:
+            self._db.execute("DELETE FROM pins WHERE track_id = ?", (track_id,))
+            self._forget_learned(track_id)
+
+    def forget_learned(self) -> None:
+        """Forget everything learned from listening; pins and settings stay."""
+        with self._db:
+            self._db.execute("DELETE FROM seeks")
+            self._db.execute("DELETE FROM samples")
+
+    def forget_all(self) -> None:
+        """Delete everything: pins, learned data, ignored tracks, settings."""
+        with self._db:
+            for table in ("pins", "seeks", "samples", "ignored", "settings"):
+                self._db.execute(f"DELETE FROM {table}")
+        self._db.execute("VACUUM")  # give the space back to the disk
+
+    # Internals --------------------------------------------------------------
+
+    def _last_listen(self, track_id: str) -> int:
+        row = self._db.execute(
+            "SELECT MAX(listen) FROM seeks WHERE track_id = ?", (track_id,)
+        ).fetchone()
+        return row[0] or 0
+
+    def _keep_recent(self, track_id: str) -> None:
+        # The heatmap only reads the RECENT_LISTENS latest listens with seeks.
+        self._db.execute(
+            "DELETE FROM seeks WHERE track_id = ? AND listen NOT IN ("
+            " SELECT DISTINCT listen FROM seeks WHERE track_id = ?"
+            " ORDER BY listen DESC LIMIT ?)",
+            (track_id, track_id, RECENT_LISTENS),
+        )
+
+    def _forget_learned(self, track_id: str) -> None:
+        self._db.execute("DELETE FROM seeks WHERE track_id = ?", (track_id,))
+        self._db.execute("DELETE FROM samples WHERE track_id = ?", (track_id,))
+
+    def _setting(self, key: str) -> int:
+        row = self._db.execute(
+            "SELECT value FROM settings WHERE key = ?", (key,)
+        ).fetchone()
+        return row[0] if row else 0
+
+    def _set_setting(self, key: str, value: int) -> None:
+        self._db.execute(
+            "INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)", (key, value)
+        )