THE ORGAN PLAYBACK ENGINE
=========================

NITETIME ORGAN SYSTEM // PLAYBACK, ROTATION AND REGISTRATION

The playback controller is the part of the system that turns a catalog into
a broadcast. It chooses a performance, starts the MIDI player, follows the
physical result, records the outcome and prepares the next transition.


REQUESTS FIRST
==============

The intended order is simple:

    approved queued request
        -> otherwise random catalog selection

Queued requests are consumed oldest-first. A request can carry an on-air
label such as NEW MIDI REQUEST without replacing the song's authoritative
metadata.

The queue exists in the application, but public queue administration is
deliberately not exposed as an unauthenticated web feature. A future request
line must validate known catalog identities, moderate new material and keep
an audit record.


ANTI-REPEAT ROTATION
====================

Random selection avoids the currently supplied hash and consults recent
playback history. It prefers content that has not appeared in the recent
rotation. If the library is too small to satisfy that rule, the controller
falls back to the playable set rather than stopping the station.

The current rule is content-based. Alternate arrangements can therefore
appear close together even when they share a composition or title. A future
composition ID would allow stronger musical anti-repeat behavior.


OUTCOMES
========

Every attempt receives an outcome:

    finished    the player ended normally
    skipped     an operator advanced the broadcast
    stopped     the controller was shutting down
    timeout     a safety limit was exceeded
    error       the player failed to start or exited unsuccessfully

The controller does not confuse a skipped song with a bad song. Skipping is
a playback event; disabling or quarantining is a curation decision.


MIDI SAFETY
==========

After every performance, including interruption and failure, the controller
sends a MIDI panic across all channels. It releases notes and clears pedal
state so a stuck note does not continue beneath the next song.

The active player is treated as a child of the controller. Stopping or
skipping the controller also terminates the active playback group before
the next state is published.


REGISTRATIONS
=============

The system can change approved instrument programs during long pieces. The
interval is calculated from the first tempo and meter, expressed in musical
bars, and bounded so an unusual score cannot cause constant switching.

If a source MIDI already contains its own program changes, those authored
voices are preserved and random changes are disabled for that song. Rhythm
channel data is excluded from melodic program changes.

The configuration can also retain captured hardware registration messages.
Those messages are validated before transmission and remain an approved set,
not arbitrary data from the public internet.


STATION IDS
===========

Short station-identification MIDI pieces live outside the catalog. They do
not appear as ordinary UP NEXT songs. After a normally finished song, one
may play between the pieces; skipped, stopped, timed-out and failed songs do
not trigger the interstitial.

During an interstitial, the public state identifies that the station is in a
transition. The main song card hides so a station ID is not misrepresented
as a catalog performance.


THE OPERATOR BOUNDARY
=====================

The controller has restart, stop and skip behavior for the station operator.
It does not expose shell execution, arbitrary file paths or database
editing through the display server. Playback control and public presentation
are separate concerns.

That separation is what lets the organ play continuously without making the
whole machine a public remote control.