FROM SHEET MUSIC TO THE ORGAN
=============================

NITETIME ORGAN SYSTEM // INTAKE AND CONVERSION

There are two different ways music enters the organ system. A ready-made
MIDI file is not the same thing as a printed score, MusicXML document or
scanned image. They have different validation requirements and different
failure modes.


READY-MADE MIDI
===============

A staged MIDI file is inspected before it enters the live library.

The importer:

    calculates a content hash
    parses the MIDI structure
    requires a useful number of notes
    requires a reasonable duration
    checks for exact duplicates
    trims only a long silent tail when appropriate
    gives the accepted file a safe library name
    archives the original source
    writes a review report
    scans the library for the new content

The importer does not rewrite the musical performance before the final
audible event. A sparse or incomplete arrangement can pass file validation
and still need to be rejected after somebody listens to it.

That distinction matters. A file can be technically valid, readable by a
MIDI parser and playable by the organ while still being musically wrong.


PRINTED OR STRUCTURED SCORES
============================

MusicXML is the preferred score source. A ZIP package may contain MusicXML
and reference material. Direct MusicXML and compatible score files are also
accepted. PDFs and image scans use an optical-recognition step and are less
reliable, especially when handwriting or complex notation is involved.

The score pipeline broadly does this:

    source arrives
        -> stable work copy
        -> safe extraction when packaged
        -> notation recognition when necessary
        -> MusicXML selection
        -> LilyPond/MIDI conversion
        -> simultaneous-staff correction
        -> technical validation
        -> review report
        -> atomic library placement
        -> catalog scan

Archive and review stages preserve provenance. A failed conversion produces
a short explanation instead of disappearing into a generic error folder.


VALIDATION
==========

Generated MIDI is checked for duration, channels and note events. Where a
score provides a reliable duration, the generated performance is compared
against it within a broad tolerance. Unsupported timing models and unreadable
files are rejected rather than guessed into rotation.

The pipeline also protects against unsafe packaged input. Absolute paths and
parent-directory traversal are rejected before archive members are considered.
Only expected score and reference file types are processed.


THE RACE PROBLEM
================

The intake system can be noticed by both a filesystem watcher and a periodic
safety sweep. Both may see the same source. The source is copied into a
content-addressed work area before conversion, but two workers can still race
while archiving the original.

The practical lesson is that duplicate success/error messages do not always
mean duplicate music. They can mean one worker accepted the source while a
second worker lost the race to move it.

Serializing the one-shot conversion is a planned hardening step.


AUDIO EXPERIMENTS
=================

Audio-to-MIDI experiments exist as a separate path. Their results do not
automatically enter the broadcast rotation. They must be auditioned,
deliberately imported, cataloged and curated.

Passing a file-format test is not the same as sounding good on the organ.
The quarantine shelf contains evidence that this rule is necessary.


THE HUMAN CHECK
===============

The conversion machine can answer:

    Can this file be parsed?
    Does it contain notes?
    Is its duration plausible?
    Can the organ receive it?

Only a listener can reliably answer:

    Does the arrangement make musical sense?
    Did the chorus survive?
    Are the staves playing together?
    Is the result worth putting on the air?

The last stage of conversion is therefore still listening.