# Development Log

This file records the app's architecture and the implementation choices made
to improve startup and queue responsiveness. It describes intended behavior;
no formal performance benchmark has been run.

## Architecture

- `mpvremote/config.py` is the central settings module. It defines the mpv IPC
  socket path, supported video extensions, key bindings, app version, and media
  directory. The media directory defaults to `~/Videos`; an override is read
  from `~/.config/mpvremotemedia` and can be edited in Settings.
- `mpvremote/mpv_client.py` sends JSON commands to mpv over its Unix-domain IPC
  socket and decodes JSON responses.
- `mpvremote/views.py` contains the curses views:
  - `MainView` provides playback controls and status.
  - `PlaylistView` displays and edits mpv's current playlist.
  - `QueueView` searches the configured media library and queues files.
  - `SettingsView` edits the media-directory setting.
  - `AboutView` displays app information and key bindings.
- `mpvremote/app.py` initializes curses, constructs the views, owns the media
  cache and scan worker, and coordinates drawing and input in the application
  loop.
- `mpvremote/__init__.py` exports `App` and `SOCKET`. Running
  `python3 -m mpvremote` loads the package and enters `mpvremote/__main__.py`.
  The entry point handles `--help`, checks that the configured socket exists,
  then uses `curses.wrapper` to set up and restore the terminal. The app enables
  keypad mode and handles input through its `getch()` loop.

## Startup and media scanning

The initial recursive media scan runs on a background worker instead of
blocking `App` initialization. The worker scans immediately and waits 120
seconds between subsequent scans. An event marks completion of the first scan.
If Queue is opened before that scan completes, it displays a scanning message
and populates automatically when the scan publishes its results.

The scan commits an immutable tuple of entries containing the display name,
absolute path, and a pre-normalized `casefold()` name. Cache replacement and
version increments happen under a lock. `get_videos_with_version()` returns
the snapshot and version together; `get_videos()` retains the simpler
`(name, path)` interface for other callers.

## Responsiveness changes

### Escape-key decoding

After curses initializes, the app requests a 50 ms Escape-sequence delay using
`curses.set_escdelay()`, when the platform supports it. This reduces the wait
when Escape is pressed while retaining a short interval for distinguishing
Escape from terminal key sequences such as arrows.

### Queue filtering and rendering

`QueueView` caches its indexed media snapshot and filtered results. Filtering
runs only when the search query or media-cache version changes; rendering does
not rescan or refilter the list. While Queue is active, the event loop uses a
100 ms input timeout and calls the view's update hook, allowing completed
background scans to appear without requiring a keypress. Other views continue
to wait for input normally.

## User-level installation

The root `Makefile` provides `install`, `verify`, and `uninstall` targets.
Installation copies the package beneath `~/.local/share/mpvremote` and creates
an executable `~/.local/bin/mpvremote` wrapper that sets `PYTHONPATH` and runs
`python3 -m mpvremote`. It does not edit shell startup files; it prints a PATH
instruction when needed. The verification target runs the installed launcher
with `--help`, which does not require mpv to be running.

## Known performance limits

The main view still retrieves playback status properties synchronously through
mpv IPC. Those requests have not been batched or moved to a background poller;
they remain a possible area for future profiling and optimization.