Merge pull request 'webui: a grouped keyboard shortcut panel for the sheet' (#33) from sheet-shortcuts into sheet-editing

Reviewed-on: #33
Reviewed-by: branderson <brad@branderson.io>

.dejima/allowed-domains

@@ -0,0 +1,6 @@
+deb.debian.org
+security.debian.org
+pypi.org
+files.pythonhosted.org
+download.pytorch.org
+download-r2.pytorch.org

.gitea/workflows/tests.yml

@@ -0,0 +1,86 @@
+name: tests
+
+# `pull_request_target` reads this file from the base branch, so a pull
+# request cannot change what runs or where (including `runs-on:`). The run's
+# ref is therefore the base branch, and the checkout has to name the head.
+on:
+  pull_request_target:
+
+jobs:
+  test:
+    # No Docker socket, and egress limited to .dejima/allowed-domains on main.
+    runs-on: dejima-confined
+
+    # Node for actions/checkout; Debian bookworm's python3 is the 3.11 the
+    # Dockerfile ships.
+    container:
+      image: node:22-bookworm
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      # Inline rather than a script in the repository: the files come from the
+      # branch under test, so a script would be missing from older branches.
+      - name: Check the hosts this job fetches from are reachable
+        run: |
+          set -u
+          bad=""
+          for host in deb.debian.org security.debian.org pypi.org \
+                      files.pythonhosted.org download.pytorch.org \
+                      download-r2.pytorch.org; do
+            resolved=""
+            for attempt in 1 2 3 4; do
+              getent hosts "$host" >/dev/null 2>&1 && { resolved=yes; break; }
+              sleep 2
+            done
+            if [ -z "$resolved" ]; then
+              echo "no    $host - does not resolve"; bad="$bad $host(dns)"; continue
+            fi
+            # Any HTTP answer proves the connection; curl reports 000 for none.
+            code="$(curl -sS -o /dev/null --max-time 20 --retry 2 -w '%{http_code}' "https://$host/" 2>/dev/null || true)"
+            case "${code:-000}" in
+              000) echo "no    $host - resolves, but nothing answered over https"
+                   bad="$bad $host(net)" ;;
+              *)   echo "ok    $host (http $code)" ;;
+            esac
+          done
+          [ -z "$bad" ] && exit 0
+          {
+            echo
+            echo "Unreachable:$bad"
+            echo
+            echo "The confined tier reaches only what .dejima/allowed-domains on"
+            echo "main declares, rendered onto the runner separately from the"
+            echo "merge. On the runner:"
+            echo "  sudo dejima-ci-allowlist show    - is the name listed?"
+            echo "  sudo dejima-ci-allowlist check   - is a change pending?"
+            echo "  sudo dejima-ci-allowlist render  - apply it now"
+            echo "A (dns) failure is the resolver; a (net) one is the packet"
+            echo "filter, which sudo dejima-ci-firewall reapplies."
+            echo
+            echo "download.pytorch.org redirects its wheels to"
+            echo "download-r2.pytorch.org, so both have to be allowed."
+          } >&2
+          exit 1
+
+      - name: Install Python
+        run: |
+          apt-get update
+          apt-get install -y --no-install-recommends python3 python3-venv
+          python3 -m venv /opt/venv
+          # bookworm's pip 23.0 rejects the PyTorch index's typing_extensions
+          # wheel over its name's spelling, then cannot build it from source
+          /opt/venv/bin/pip install --retries 5 --upgrade pip
+          echo /opt/venv/bin >> "$GITHUB_PATH"
+
+      # The CPU build first: torch from PyPI is the CUDA build, several GB of
+      # libraries no test uses. The install below then finds torch satisfied.
+      - name: Install CPU-only torch
+        run: pip install --retries 5 torch torchaudio --index-url https://download.pytorch.org/whl/cpu
+
+      - name: Install songtrace
+        run: pip install --retries 5 -e '.[dev]'
+
+      - run: pytest

Dockerfile

@@ -11,9 +11,9 @@ COPY pyproject.toml ./
 COPY src ./src
 RUN pip install --no-cache-dir .
 
-ENV KARAOKE_MAKER_CONFIG=/config/config.toml \
+ENV SONGTRACE_CONFIG=/config/config.toml \
     TORCH_HOME=/data/models \
     XDG_CACHE_HOME=/data/models/cache
 
 EXPOSE 8000
-CMD ["karaoke-maker", "serve"]
+CMD ["songtrace", "serve"]

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published
+    by the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

README.md

@@ -1,17 +1,22 @@
-# karaoke-maker
+# songtrace
+
+Turn a song and its lyrics into a playable UltraStar chart.
 
 A CLI and minimal web UI that turns a song — title, artist, lyrics you supply,
 and a YouTube URL or local video file — into a playable
-[UltraStar](https://usdx.eu/format/)-format song folder for
-[Melody Mania](https://melodymania.net/), a commercial UltraStar Deluxe fork.
+[UltraStar](https://usdx.eu/format/)-format song folder. Also compatible with
+[Melody Mania](https://melodymania.org/).
+
+![Web UI](docs/images/webui.png)
 
 The pipeline:
 
 1. **acquire** — download audio/video via `yt-dlp` (or use a local video file)
 2. **separate** — split vocals/instrumental with Demucs
-3. **transcribe** — send the vocal stem to your own intranet OpenAI-compatible
-   Whisper server, as a sanity check that the supplied lyrics match the audio
-   and to locate vocal sections
+3. **transcribe** — send the vocal stem to your own intranet Whisper server
+   (OpenAI-compatible, or [onerahmet/openai-whisper-asr-webservice](https://github.com/ahmetoner/whisper-asr-webservice)),
+   as a sanity check that the supplied lyrics match the audio and to locate
+   vocal sections
 4. **align** — forced-align the *supplied* reference lyrics against the vocal
    stem with wav2vec2 (torchaudio's MMS_FA) to get word timings
 5. **pitch** — track pitch on the vocal stem with torchcrepe
@@ -26,16 +31,70 @@ output.
 **The output is a best-effort draft**, not a finished song. Every run ends by
 printing the low-confidence regions it found (e.g.
 `3 low-confidence notes near 0:42–0:47`) — open the result in an UltraStar
-editor such as [Yass](http://www.yass-hq.de/) or
+editor such as [Yass](https://www.yass-along.com/) or
 [USDX](https://usdx.eu/) and touch those spots up before playing.
 
+## Reviewing a song
+
+The web UI plays the finished song folder back against the review, so you can
+check the timing without loading it into a game first. Pick a song in the
+queue and the review panel gets the packaged video with a transport above the
+lyrics; as it plays, the line being sung is highlighted, words light up as
+they are reached, and a playhead sweeps each line against its notes. Click any
+line or word to play from there.
+
+Playback is modelled on the game: the `#MP3` is the audio and the clock, and
+the `#VIDEO` is muted background slaved to it. It also uses the same seconds
+the notes were generated from, so a word that lights up late in the browser is
+late in the game too.
+
+The packaged video has its audio track stripped for the same reason. It is the
+same recording as the `#MP3`, so a player that does not mute the video plays
+both at once, a few frames apart, which is heard as an echo. Songs built
+before this change still have it — check with `ffprobe <song>.mp4` for an
+audio stream, and rebuild with **Restart from** set to `package` to clear it
+without re-downloading.
+
+## Editing a song
+
+Above the lyrics, the note sheet shows one line at a time on a pitch-by-beat
+grid, with the pitch songtrace detected drawn over the notes: where a note is
+right the curve runs through it, so a wrong one stands out. Fix it there and
+**SAVE LINE**; the song folder's chart is rewritten on the spot.
+
+Drag a note to move it and its ends to resize it; everything snaps to the
+chart's beat grid and to semitones. Double-click empty space to add a note,
+or a note to change its syllable. With the sheet focused: ←/→ move, ↑/↓
+change pitch (Shift for an octave), Shift+←/→ change length, Tab selects the
+next note, S splits, M merges with the next note, G/F/R make a note golden,
+freestyle or rap, Delete removes, Ctrl+Z undoes, Ctrl+S saves and P plays
+the line.
+
+The ↵ markers either side of a line are its line breaks: drag one to move it
+(it snaps to beats and stays between the lines it separates) and double-click
+one to put it back where songtrace places it. Moving a break does not mark
+either line's notes as edited, so they still follow a rebuild.
+
+The **GRID** bar above the notes sets the chart's BPM and GAP. Changes redraw
+the grid as you type and are charted on **APPLY**; ×2 and ÷2 fix a tempo
+detected at double or half speed, and **ALIGN TO NOTE** moves GAP the least
+that puts the selected note on a beat. Notes keep their timing in seconds and
+re-snap to the new grid. **RESET** returns to the BPM songtrace chose (your
+BPM override, or the detected tempo) with GAP at the first note.
+
+Edits survive every rebuild, REBUILD ALL FROM… included: they are kept apart
+from what the pipeline generates and laid back over it each time. **REVERT**
+returns a line to the generated notes. Changing a line's lyrics sets its edit
+aside rather than applying it to different words; the sheet lists those so
+you can discard them.
+
 ## Configuration
 
 Config is TOML. Resolution order:
 
 1. `--config <path>` passed explicitly on the command line
-2. the `KARAOKE_MAKER_CONFIG` environment variable
-3. `~/.config/karaoke-maker/config.toml`
+2. the `SONGTRACE_CONFIG` environment variable
+3. `~/.config/songtrace/config.toml`
 
 Copy the example and fill in your Whisper server:
 
@@ -45,8 +104,17 @@ $EDITOR config.toml   # set whisper_url at minimum
 ```
 
 See `config.example.toml` for every available field (`whisper_url`,
-`whisper_api_key`, `whisper_model`, `output_dir`, `work_dir`, `creator`,
-`demucs_model`, `crepe_model`, `device`, `bind_host`, `port`).
+`whisper_api_key`, `whisper_model`, `whisper_api`, `output_dir`, `work_dir`,
+`creator`, `demucs_model`, `crepe_model`, `device`, `bind_host`, `port`,
+`ytdlp_clients`, `ytdlp_cookies`, `ytdlp_impersonate`,
+`ytdlp_pot_provider_url`, `ytdlp_version`).
+
+`whisper_api` selects the wire format: `"openai"` (default) speaks the
+OpenAI-compatible `POST {whisper_url}/audio/transcriptions` API; `"asr-webservice"`
+speaks [onerahmet/openai-whisper-asr-webservice](https://github.com/ahmetoner/whisper-asr-webservice)'s
+`POST {whisper_url}/asr` API instead (point `whisper_url` at that server's base
+URL with no `/v1` suffix — `whisper_model`/`whisper_api_key` are unused for
+this backend, since the model is fixed by how that server was started).
 
 ## Docker
 
@@ -63,7 +131,7 @@ container recreation.
 Run the CLI inside the container instead of the web UI:
 
 ```sh
-docker compose run --rm karaoke-maker karaoke-maker make \
+docker compose run --rm songtrace songtrace make \
   --title "Song Title" --artist "Artist Name" \
   --lyrics /data/lyrics.txt --youtube https://youtu.be/...
 ```
@@ -73,21 +141,45 @@ Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/)
 installed on the host; `docker-compose.yml` requests one GPU via the
 `nvidia` device driver.
 
+## Sharing the GPU
+
+`songtrace serve` is long-lived but only wants the GPU in bursts, so it hands
+it back after every stage rather than holding it for the life of the process.
+Three stages load a model — `separate` (Demucs), `align` (wav2vec2) and
+`pitch` (torchcrepe) — and each one's weights are dropped as soon as that
+stage finishes, followed by `torch.cuda.empty_cache()` to return the
+allocator's freed blocks to the driver instead of keeping them for reuse. This
+matters most between `separate` and `align`: `transcribe` sits between them
+waiting on your Whisper server, which can be minutes of a GPU nothing is
+using.
+
+Stages that gave memory back say so in the job log:
+
+```
+[separate] released 3704 MiB of GPU memory
+```
+
+The cost is reloading each model once per job instead of once per process,
+which is seconds against stages that run for minutes. What this does not
+release is the CUDA context itself, a few hundred MB that belongs to the
+process until it exits; freeing that would mean running each stage in a
+subprocess. If you need every last MB back, stop the container between runs.
+
 ## Bare-metal
 
 ```sh
 pip install -e .
-karaoke-maker make --help
+songtrace make --help
 ```
 
 ```
-karaoke-maker make --title TITLE --artist ARTIST --lyrics LYRICS_FILE \
+songtrace make --title TITLE --artist ARTIST --lyrics LYRICS_FILE \
   (--youtube URL | --video PATH) \
   [--genre GENRE] [--year YEAR] [--language LANGUAGE] [--cover COVER_IMAGE] \
   [--bpm BPM] [--force-from STAGE] [--config CONFIG]
 ```
 
-Run the web UI instead with `karaoke-maker serve [--config CONFIG]`.
+Run the web UI instead with `songtrace serve [--config CONFIG]`.
 
 ## Re-running a stage
 
@@ -98,9 +190,88 @@ stage and everything after it, reusing the cached output of everything
 before it:
 
 ```sh
-karaoke-maker make --title "..." --artist "..." --lyrics lyrics.txt \
+songtrace make --title "..." --artist "..." --lyrics lyrics.txt \
   --youtube https://youtu.be/... --force-from align
 ```
 
 Valid stages, in pipeline order: `acquire`, `separate`, `transcribe`,
 `align`, `pitch`, `notes`, `grid`, `package`.
+
+In the web UI this is what selecting a queue entry does: its title, artist,
+lyrics and the rest come back up in the form, so you can adjust them and hit
+REBUILD SONG. Only the stages your edit actually invalidates are rerun —
+fixing a line of lyrics realigns without re-downloading or re-separating.
+CREATE SONG, at the top of the queue, clears the page to start a fresh one.
+
+That planning works off the fields you changed, which cannot see a change in
+songtrace itself: after an upgrade, a rebuild of an older song finds every
+stage cached and does nothing. **Restart from** on the rebuild form is the way
+to redo a stage anyway — pick `package` to repackage without re-downloading.
+It can only widen what is rerun, so an edit that invalidates an earlier stage
+still wins.
+
+**REBUILD ALL FROM…**, under CREATE SONG, does the same for every song at once:
+pick the stage an update improved and each song is rebuilt from there with the
+inputs it has now. Every song starts ticked; untick any already rebuilt by hand
+(each shows when it was last built). Songs still in progress are skipped, as
+are songs whose uploaded video is gone when the stage is `acquire`.
+
+## YouTube download failures
+
+`HTTP Error 403: Forbidden` from the acquire stage means YouTube served the
+page but refused the media URL. In rough order of likelihood:
+
+1. **yt-dlp is stale.** YouTube changes its defences every few weeks, so
+   songtrace keeps yt-dlp current itself. Once a day, and again whenever a
+   download fails outright, it checks PyPI for a newer stable release,
+   installs it under `$XDG_CACHE_HOME/songtrace/` (`/data/models/cache` in the
+   container), and tries it before the copy installed with songtrace. That
+   copy is never modified and is always the fallback, so a release that breaks
+   compatibility costs a retry rather than the download. The job log names
+   the yt-dlp version behind each attempt.
+
+   `ytdlp_version` overrides this: `"bundled"` uses only the installed copy,
+   and a release number such as `"2026.08.19"` pins that release instead of
+   the newest.
+
+2. **Missing JS runtime.** yt-dlp needs `yt-dlp-ejs` plus a JavaScript engine
+   to solve YouTube's player challenges; without them it silently falls back to
+   formats that 403. The `[default,curl-cffi,deno]` extras in `pyproject.toml`
+   cover this, for both the installed copy and the ones fetched at runtime.
+   Check with `docker compose exec songtrace yt-dlp -v --simulate <url>` — the debug
+   header must show a `JS runtimes:` line that is not `none`.
+
+3. **The IP is rate-limited or flagged.** Datacenter and VPN ranges get
+   throttled hardest. Try from another network before changing config.
+
+4. **A PO token is required.** If the log says so explicitly, run
+   [bgutil-ytdlp-pot-provider](https://github.com/Brainicism/bgutil-ytdlp-pot-provider)
+   as a sidecar, install its plugin into the image, and point
+   `ytdlp_pot_provider_url` at it.
+
+`ytdlp_clients` retries the download against each listed player client in
+turn, so a client that YouTube has broken is skipped automatically.
+`ytdlp_cookies` (a Netscape cookie jar, for age-gated videos) and
+`ytdlp_impersonate` (a browser TLS fingerprint, e.g. `"chrome"`) are the other
+two levers. Do not use a cookie jar from an account you care about — YouTube
+bans for automated access.
+
+Failed downloads leave the work dir intact, so re-running the job resumes
+rather than starting over.
+
+## Regenerating the web UI screenshot
+
+`scripts/screenshot_webui.py` seeds the real app with a fixed set of jobs
+covering every status and screenshots it to `docs/images/webui.png`. It uses
+`ffmpeg` to give the selected song a playable folder so the shot includes the
+player; without `ffmpeg` on `PATH` it still runs, just without it.
+
+```sh
+pip install -e '.[dev]'
+playwright install chromium
+python scripts/screenshot_webui.py
+```
+
+## License
+
+[AGPLv3](LICENSE)

config.example.toml

@@ -1,6 +1,8 @@
 whisper_url = "http://whisper.intranet:9000/v1"
 # whisper_api_key = ""
 # whisper_model = "whisper-1"
+# whisper_api = "openai"  # or "asr-webservice" for onerahmet/openai-whisper-asr-webservice
+                          # (set whisper_url without the /v1 suffix, e.g. "http://whisper.intranet:9000")
 output_dir = "/data/output"
 work_dir = "/data/work"
 creator = "brad"
@@ -9,3 +11,13 @@ creator = "brad"
 # device = "cuda"
 bind_host = "0.0.0.0"
 # port = 8000
+
+# YouTube downloads. Each player client is tried in order until one works;
+# "default" means whatever yt-dlp currently picks for itself.
+# ytdlp_clients = ["default", "tv"]
+# ytdlp_cookies = "/config/youtube-cookies.txt"  # Netscape cookie jar
+# ytdlp_impersonate = "chrome"                   # TLS fingerprint to present
+# ytdlp_pot_provider_url = "http://bgutil-provider:4416"
+# Newer yt-dlp releases are fetched from PyPI at runtime and tried before the
+# bundled one; "bundled" turns that off, a release number pins one.
+# ytdlp_version = "auto"

docker-compose.yml

@@ -1,5 +1,5 @@
 services:
-  karaoke-maker:
+  songtrace:
     build: .
     ports:
       - "8000:8000"

pyproject.toml

@@ -1,10 +1,16 @@
 [project]
-name = "karaoke-maker"
+name = "songtrace"
 version = "0.1.0"
 description = "Generate UltraStar/Melody Mania karaoke songs from a video and reference lyrics"
 requires-python = ">=3.11"
+license = "AGPL-3.0-or-later"
 dependencies = [
-    "yt-dlp",
+    # yt-dlp declares no runtime deps of its own; the extras are what make
+    # YouTube work. "default" pulls yt-dlp-ejs (JS challenge solving) and the
+    # requests/urllib3 handlers, "deno" ships the JS runtime that executes it,
+    # and "curl-cffi" provides the --impersonate targets. Without them YouTube
+    # extraction degrades to HTTP 403 on the media URLs.
+    "yt-dlp[default,curl-cffi,deno]",
     "demucs",
     "torch",
     "torchaudio",
@@ -22,10 +28,10 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-dev = ["pytest"]
+dev = ["pytest", "playwright"]
 
 [project.scripts]
-karaoke-maker = "karaoke_maker.cli:main"
+songtrace = "songtrace.cli:main"
 
 [build-system]
 requires = ["setuptools>=68"]
@@ -35,7 +41,7 @@ build-backend = "setuptools.build_meta"
 where = ["src"]
 
 [tool.setuptools.package-data]
-karaoke_maker = ["static/*", "static/fonts/*"]
+songtrace = ["static/*", "static/fonts/*"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

scripts/screenshot_webui.py

@@ -0,0 +1,256 @@
+"""Regenerate docs/images/webui.png against the current web UI.
+
+Seeds the real app (via create_app's fake-runner seam, same as tests/test_web.py)
+with a fixed set of jobs covering every status, then screenshots it.
+
+One-time setup: pip install -e '.[dev]' && playwright install chromium
+Run: python scripts/screenshot_webui.py
+"""
+import json
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+from pathlib import Path
+
+import httpx
+import uvicorn
+from playwright.sync_api import sync_playwright
+
+from songtrace.config import Config
+from songtrace.pipeline import PipelineError, PipelineResult, song_slug
+from songtrace.web import create_app
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+OUT_IMAGE = REPO_ROOT / "docs" / "images" / "webui.png"
+STAGES = ["acquire", "separate", "transcribe", "align", "pitch", "notes", "grid", "package"]
+DEFAULT_LYRICS = "[verse]\n...\n[chorus]\n...\n"
+
+# public domain (16th century English folk song, author unknown)
+GREENSLEEVES_LYRICS = """\
+Alas, my love, you do me wrong
+To cast me off discourteously
+For I have loved you well and long
+Delighting in your company
+
+Greensleeves was all my joy
+Greensleeves was my delight
+Greensleeves was my heart of gold
+And who but my lady Greensleeves
+
+I have been ready at your hand
+To grant whatever you would crave
+I have both waged life and land
+Your love and good will for to have
+
+Greensleeves was all my joy
+Greensleeves was my delight
+Greensleeves was my heart of gold
+And who but my lady Greensleeves
+"""
+
+# order matters: the app has one worker thread, so each job runs in submission
+# order. "running" must be submitted after the done/failed ones complete and
+# before "queued", so it's the one still in progress when "queued" arrives.
+SONGS = [
+    ("Every Single Night", "Fiona Apple", "done",
+     {"warnings": ["1 low-confidence note near 2:41–2:44"]}),
+    ("This Year", "The Mountain Goats", "done", {"warnings": []}),
+    ("Pink Moon", "Nick Drake", "done",
+     {"warnings": ["2 low-confidence notes near 0:38–0:41",
+                    "1 low-confidence note near 1:22–1:24"]}),
+    ("Landslide", "Fleetwood Mac", "done",
+     {"warnings": ["1 low-confidence note near 0:52–0:55"]}),
+    ("Greensleeves", "Traditional", "done",
+     {"lyrics": GREENSLEEVES_LYRICS,
+      "warnings": ["1 low-confidence note near 0:45–0:47",
+                   "1 line dropped (not sung) near \"for i have loved\"",
+                   "missing lyrics near 2:10–2:18"],
+      "review": {
+          "lines": [
+              # Pitches are the real Greensleeves melody (E natural minor, as
+              # arranged by Gilbert DeBenedetti, "Level 4 - Flowing"), converted
+              # to UltraStar semitones (0 = C4 = MIDI 60): E5=16 F#5=18 G5=19
+              # A5=21 B4=11 D5=14.
+              {"index": 0, "text": "Alas, my love, you do me wrong",
+               "dropped": False,
+               "notes": [{"start": 10.0, "end": 10.4, "pitch": 16, "low_confidence": False},
+                         {"start": 10.4, "end": 10.6, "pitch": 18, "low_confidence": False},
+                         {"start": 10.6, "end": 11.2, "pitch": 19, "low_confidence": False},
+                         {"start": 11.2, "end": 11.5, "pitch": 21, "low_confidence": False},
+                         {"start": 11.5, "end": 11.7, "pitch": 19, "low_confidence": False},
+                         {"start": 11.7, "end": 11.9, "pitch": 18, "low_confidence": False},
+                         {"start": 11.9, "end": 12.9, "pitch": 14, "low_confidence": False}],
+               "words": [{"text": "Alas,", "start": 10.0, "end": 10.4},
+                         {"text": "my", "start": 10.4, "end": 10.6},
+                         {"text": "love,", "start": 10.6, "end": 11.2},
+                         {"text": "you", "start": 11.2, "end": 11.5},
+                         {"text": "do", "start": 11.5, "end": 11.7},
+                         {"text": "me", "start": 11.7, "end": 11.9},
+                         {"text": "wrong", "start": 11.9, "end": 12.9}]},
+              {"index": 1, "text": "To cast me off discourteously",
+               "dropped": False,
+               "notes": [{"start": 44.0, "end": 44.3, "pitch": 11, "low_confidence": False},
+                         {"start": 44.3, "end": 44.6, "pitch": 16, "low_confidence": False},
+                         {"start": 44.6, "end": 44.8, "pitch": 18, "low_confidence": False},
+                         {"start": 44.8, "end": 45.0, "pitch": 19, "low_confidence": False},
+                         {"start": 45.0, "end": 45.4, "pitch": 18, "low_confidence": True}],
+               "words": [{"text": "To", "start": 44.0, "end": 44.3},
+                         {"text": "cast", "start": 44.3, "end": 44.6},
+                         {"text": "me", "start": 44.6, "end": 44.8},
+                         {"text": "off", "start": 44.8, "end": 45.0},
+                         {"text": "discourteously", "start": 45.0, "end": 45.4}]},
+              {"index": 2, "text": "For I have loved you well and long",
+               "dropped": True, "notes": [], "words": []},
+          ],
+          "missing_spans": [{"start": 130.0, "end": 138.0}],
+      }}),
+    ("Such Great Heights", "The Postal Service", "failed",
+     {"error": "yt-dlp: unable to download video data: HTTP Error 403: Forbidden"}),
+    ("Time Escaping", "Big Thief", "running", {}),
+    ("Vampire in the Corner", "Magdalena Bay", "queued", {}),
+]
+SELECTED = "Greensleeves"
+REVIEW_HEADING = "REVIEW"
+
+running_event = threading.Event()
+
+
+def make_runner():
+    specs = {title: (kind, extra) for title, _, kind, extra in SONGS}
+
+    def runner(inp, cfg, log=print, force_from=None, stages=None):
+        kind, extra = specs[inp.title]
+        if kind == "done":
+            for s in STAGES:
+                log(f"[{s}] running")
+            if "review" in extra:
+                work = cfg.work_dir / song_slug(inp)
+                work.mkdir(parents=True, exist_ok=True)
+                notes = [
+                    {**n, "duration": n["end"] - n["start"], "text": "~",
+                     "line_index": line["index"]}
+                    for line in extra["review"]["lines"] for n in line["notes"]
+                ]
+                (work / "notes_sec.json").write_text(json.dumps({
+                    "notes": notes, "breaks": [], "warnings": extra["warnings"]}))
+                (work / "align_meta.json").write_text(json.dumps({
+                    "dropped_lines": [line["index"] for line in extra["review"]["lines"]
+                                      if line["dropped"]],
+                    "missing_spans": [[s["start"], s["end"]]
+                                      for s in extra["review"]["missing_spans"]],
+                }))
+                (work / "alignment.json").write_text(json.dumps([
+                    {"word": w["text"], "start": w["start"], "end": w["end"],
+                     "score": 0.9, "line_index": line["index"]}
+                    for line in extra["review"]["lines"] for w in line.get("words", [])
+                ]))
+            out = cfg.output_dir / f"{inp.artist} - {inp.title}"
+            out.mkdir(parents=True, exist_ok=True)
+            return PipelineResult(output_dir=out, warnings=extra["warnings"])
+        if kind == "failed":
+            log("[acquire] running")
+            raise PipelineError(extra["error"])
+        for s in ["acquire", "separate", "transcribe", "align"]:
+            log(f"[{s}] running")
+        running_event.wait()
+        return PipelineResult(output_dir=cfg.output_dir / "x", warnings=[])
+
+    return runner
+
+
+def start_server(tmp_path: Path) -> tuple[str, Config]:
+    cfg = Config(whisper_url="http://localhost:9000/v1", output_dir=tmp_path / "out",
+                 work_dir=tmp_path / "work", bind_host="127.0.0.1", port=8811)
+    app = create_app(cfg, runner=make_runner())
+    server = uvicorn.Server(uvicorn.Config(app, host=cfg.bind_host, port=cfg.port,
+                                            log_level="warning"))
+    threading.Thread(target=server.run, daemon=True).start()
+    return f"http://{cfg.bind_host}:{cfg.port}", cfg
+
+
+def install_media(cfg: Config) -> bool:
+    """Give the selected song a playable folder, so the shot shows the player.
+
+    A flat fill rather than a test pattern: the point is the transport and the
+    lyric tracking underneath it, not the picture. Skipped without ffmpeg.
+    """
+    if shutil.which("ffmpeg") is None:
+        print("ffmpeg not found; screenshotting without the player")
+        return False
+    artist, title = next((a, t) for t, a, _, _ in SONGS if t == SELECTED)
+    slug = f"{artist} - {title}"
+    out = cfg.output_dir / slug
+    out.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        ["ffmpeg", "-y", "-loglevel", "error", "-f", "lavfi",
+         "-i", "color=c=0x1A1430:s=640x360:d=60", "-c:v", "libx264",
+         "-pix_fmt", "yuv420p", "-preset", "ultrafast", "-an",
+         str(out / f"{slug}.mp4")], check=True)
+    subprocess.run(
+        ["ffmpeg", "-y", "-loglevel", "error", "-f", "lavfi",
+         "-i", "anullsrc=r=44100:cl=stereo:d=60", "-b:a", "64k",
+         str(out / f"{slug}.mp3")], check=True)
+    (out / f"{slug}.txt").write_text(
+        f"#TITLE:{title}\n#ARTIST:{artist}\n#MP3:{slug}.mp3\n#VIDEO:{slug}.mp4\n"
+        f"#BPM:240\n#GAP:10000\n: 0 4 16 Alas,\nE\n", encoding="utf-8")
+    return True
+
+
+def seed_jobs(base_url: str) -> None:
+    with httpx.Client(timeout=10) as client:
+        for title, artist, kind, extra in SONGS:
+            resp = client.post(f"{base_url}/api/jobs", data={
+                "title": title, "artist": artist,
+                "lyrics": extra.get("lyrics", DEFAULT_LYRICS),
+                "youtube_url": "https://youtu.be/00000000000"})
+            resp.raise_for_status()
+            job_id = resp.json()["id"]
+            if kind == "queued":
+                continue
+            for _ in range(200):
+                job = client.get(f"{base_url}/api/jobs/{job_id}").json()
+                if kind == "running" and job["stage"] == "align":
+                    break
+                if job["status"] in ("done", "failed"):
+                    break
+                time.sleep(0.05)
+
+
+def capture(base_url: str, with_player: bool) -> None:
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        page = browser.new_page(viewport={"width": 1280, "height": 1000})
+        page.goto(base_url, wait_until="networkidle")
+        page.get_by_text(SELECTED, exact=True).click()
+        page.wait_for_timeout(500)
+        if with_player:
+            # paused mid-line, so the shot carries the playhead and the sung /
+            # current word colouring rather than an untouched transport
+            page.evaluate("document.getElementById('player-media').currentTime = 11.6")
+            page.wait_for_timeout(400)
+            # scrolled to the review: the player pins to the top of #main and
+            # the tracked lines sit under it, which is the panel in use
+            page.evaluate("""() => {
+              const main = document.getElementById('main');
+              main.scrollTo(0, document.getElementById('review').offsetTop - 12);
+            }""")
+            page.wait_for_timeout(400)
+        OUT_IMAGE.parent.mkdir(parents=True, exist_ok=True)
+        page.screenshot(path=str(OUT_IMAGE))
+        browser.close()
+
+
+def main() -> None:
+    with tempfile.TemporaryDirectory() as tmp:
+        base_url, cfg = start_server(Path(tmp))
+        time.sleep(1)
+        seed_jobs(base_url)
+        with_player = install_media(cfg)
+        capture(base_url, with_player)
+    print(f"wrote {OUT_IMAGE}")
+
+
+if __name__ == "__main__":
+    main()

src/karaoke_maker/config.py

@@ -1,36 +0,0 @@
-import os
-import tomllib
-from dataclasses import dataclass, fields
-from pathlib import Path
-
-
-@dataclass
-class Config:
-    whisper_url: str
-    whisper_api_key: str | None = None
-    whisper_model: str = "whisper-1"
-    output_dir: Path = Path("output")
-    work_dir: Path = Path("work")
-    creator: str = "karaoke-maker"
-    demucs_model: str = "htdemucs_ft"
-    crepe_model: str = "full"
-    device: str = "cuda"
-    bind_host: str = "127.0.0.1"
-    port: int = 8000
-
-
-_PATH_FIELDS = {"output_dir", "work_dir"}
-
-
-def load_config(path: Path | None = None) -> Config:
-    if path is None:
-        env = os.environ.get("KARAOKE_MAKER_CONFIG")
-        path = Path(env) if env else Path.home() / ".config/karaoke-maker/config.toml"
-    data = tomllib.loads(Path(path).read_text())
-    known = {f.name for f in fields(Config)}
-    unknown = set(data) - known
-    if unknown:
-        raise ValueError(f"unknown config keys: {', '.join(sorted(unknown))}")
-    for key in _PATH_FIELDS & set(data):
-        data[key] = Path(data[key])
-    return Config(**data)

src/karaoke_maker/stages/acquire.py

@@ -1,54 +0,0 @@
-import json
-import shutil
-from pathlib import Path
-
-from ..media import ffmpeg
-from ..pipeline import Ctx, PipelineError, Stage
-
-IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp", ".avif", ".gif"}
-
-
-def _classify_downloads(dest: Path) -> tuple[Path, Path | None]:
-    files = list(dest.glob("source_video.*"))
-    thumbs = [p for p in files if p.suffix.lower() in IMAGE_EXTENSIONS]
-    videos = [p for p in files if p.suffix.lower() not in IMAGE_EXTENSIONS]
-    if not videos:
-        raise PipelineError("yt-dlp produced no video file")
-    video = max(videos, key=lambda p: p.stat().st_size)
-    return video, thumbs[0] if thumbs else None
-
-
-def download_youtube(url: str, dest: Path) -> tuple[Path, Path | None]:
-    import yt_dlp
-    opts = {
-        "outtmpl": str(dest / "source_video.%(ext)s"),
-        "format": "bestvideo*+bestaudio/best",
-        "writethumbnail": True,
-        "noplaylist": True,
-    }
-    with yt_dlp.YoutubeDL(opts) as ydl:
-        ydl.extract_info(url, download=True)
-    return _classify_downloads(dest)
-
-
-def _run(ctx: Ctx) -> None:
-    if bool(ctx.inp.youtube_url) == bool(ctx.inp.video_path):
-        raise PipelineError("provide exactly one of youtube_url / video_path")
-    thumb = None
-    if ctx.inp.youtube_url:
-        video, thumb = download_youtube(ctx.inp.youtube_url, ctx.work)
-    else:
-        video = ctx.work / f"source_video{ctx.inp.video_path.suffix}"
-        shutil.copyfile(ctx.inp.video_path, video)
-    ffmpeg("-i", str(video), "-vn", "-ac", "2", "-ar", "44100",
-           str(ctx.work / "audio.wav"))
-    meta = {"video_file": video.name, "thumbnail": thumb.name if thumb else None}
-    (ctx.work / "meta.json").write_text(json.dumps(meta))
-
-
-def acquire_stage() -> Stage:
-    return Stage(
-        name="acquire",
-        outputs=lambda ctx: [ctx.work / "meta.json", ctx.work / "audio.wav"],
-        run=_run,
-    )

src/karaoke_maker/stages/align.py

@@ -1,122 +0,0 @@
-import json
-from pathlib import Path
-
-from ..lyrics import RefLyrics, alignment_token, normalize_lyrics
-from ..pipeline import Ctx, PipelineError, Stage
-from .transcribe import load_transcript, lyrics_similarity, vocal_sections
-
-SIMILARITY_THRESHOLD = 0.4
-
-_model_cache = {}
-
-
-def _get_model(device: str):
-    if device not in _model_cache:
-        from torchaudio.pipelines import MMS_FA as bundle
-        _model_cache[device] = bundle.get_model().to(device)
-    return _model_cache[device]
-
-
-def force_align_section(vocals_path: Path, start: float, end: float,
-                        tokens: list[str], device: str) -> list[tuple[float, float, float]]:
-    import torch
-    import torchaudio
-    from torchaudio.pipelines import MMS_FA as bundle
-
-    waveform, sr = torchaudio.load(str(vocals_path))
-    waveform = waveform.mean(0, keepdim=True)
-    lo, hi = int(start * sr), min(int(end * sr), waveform.shape[1])
-    waveform = torchaudio.functional.resample(
-        waveform[:, lo:hi], sr, bundle.sample_rate)
-    # MMS_FA only models a-z and apostrophe; anything else becomes the star token.
-    vocab = bundle.get_dict()
-    tokens = ["".join(c if c in vocab else "*" for c in t) for t in tokens]
-    with torch.inference_mode():
-        emission, _ = _get_model(device)(waveform.to(device))
-        spans = bundle.get_aligner()(emission[0], bundle.get_tokenizer()(tokens))
-    frame = (hi - lo) / sr / emission.shape[1]
-    return [(start + s[0].start * frame,
-             start + s[-1].end * frame,
-             sum(t.score for t in s) / len(s)) for s in spans]
-
-
-def _assign_lines_to_sections(ref: RefLyrics, sections) -> list[list[int]]:
-    """Split lyric lines across vocal sections proportionally to section duration."""
-    total = sum(b - a for a, b in sections) or 1.0
-    n_lines = len(ref.lines)
-    groups, elapsed, start = [], 0.0, 0
-    for i, (a, b) in enumerate(sections):
-        elapsed += b - a
-        stop = n_lines if i == len(sections) - 1 else min(
-            n_lines, round(n_lines * elapsed / total))
-        groups.append(list(range(start, max(stop, start))))
-        start = max(stop, start)
-    return groups
-
-
-def _interpolate(rows: list[dict], lo_bound: float, hi_bound: float) -> None:
-    """Give rows left without times evenly spaced spans between their aligned neighbours."""
-    i = 0
-    while i < len(rows):
-        if rows[i]["start"] is not None:
-            i += 1
-            continue
-        j = i
-        while j < len(rows) and rows[j]["start"] is None:
-            j += 1
-        lo = rows[i - 1]["end"] if i else lo_bound
-        hi = max(rows[j]["start"] if j < len(rows) else hi_bound, lo)
-        step = (hi - lo) / (j - i)
-        for k in range(i, j):
-            rows[k]["start"] = lo + (k - i) * step
-            rows[k]["end"] = rows[k]["start"] + step
-        i = j
-
-
-def _enforce_monotonic(rows: list[dict]) -> None:
-    prev = 0.0
-    for r in rows:
-        r["start"] = max(r["start"], prev)
-        r["end"] = prev = max(r["end"], r["start"])
-
-
-def _align_section(vocals: Path, sec: tuple[float, float], words: list[tuple[str, int]],
-                   language: str | None, device: str) -> list[dict]:
-    tokens = [alignment_token(w, language) for w, _ in words]
-    alignable = [t for t in tokens if t]
-    aligned = iter(force_align_section(vocals, sec[0], sec[1], alignable, device)
-                   if alignable else [])
-    rows, blank = [], (None, None, 0.0)
-    for (word, line_index), token in zip(words, tokens):
-        start, end, score = next(aligned, blank) if token else blank
-        rows.append({"word": word, "start": start, "end": end,
-                     "score": score, "line_index": line_index})
-    _interpolate(rows, sec[0], sec[1])
-    return rows
-
-
-def _run(ctx: Ctx) -> None:
-    ref = normalize_lyrics(ctx.inp.lyrics_text)
-    segments = load_transcript(ctx)
-    sim = lyrics_similarity(segments, ref)
-    if sim < SIMILARITY_THRESHOLD:
-        raise PipelineError(
-            f"lyrics don't match audio (similarity {sim:.2f}) — "
-            "wrong lyrics or wrong recording?")
-    # normalised so an inverted span can never collapse a section onto one instant
-    sections = [(min(a, b), max(a, b)) for a, b in vocal_sections(segments)]
-    vocals = ctx.work / "vocals.wav"
-    rows = []
-    for sec, line_idxs in zip(sections, _assign_lines_to_sections(ref, sections)):
-        words = [(w, li) for li in line_idxs for w in ref.lines[li]]
-        if words:
-            rows.extend(_align_section(vocals, sec, words, ctx.inp.language,
-                                       ctx.cfg.device))
-    _enforce_monotonic(rows)
-    (ctx.work / "alignment.json").write_text(json.dumps(rows))
-
-
-def align_stage() -> Stage:
-    return Stage(name="align",
-                 outputs=lambda ctx: [ctx.work / "alignment.json"],
-                 run=_run)

src/karaoke_maker/stages/pitch.py

@@ -1,34 +0,0 @@
-from pathlib import Path
-
-import numpy as np
-
-from ..pipeline import Ctx, Stage
-
-
-def track_pitch(vocals_path: Path, model: str, device: str):
-    import torchaudio
-    import torchcrepe
-
-    waveform, sr = torchaudio.load(str(vocals_path))
-    waveform = waveform.mean(0, keepdim=True)
-    waveform = torchaudio.functional.resample(waveform, sr, 16000)
-    f0, periodicity = torchcrepe.predict(
-        waveform, 16000, hop_length=160, model=model,
-        fmin=50.0, fmax=1100.0, device=device,
-        return_periodicity=True, batch_size=512)
-    f0 = f0[0].cpu().numpy()
-    conf = periodicity[0].cpu().numpy()
-    times = np.arange(len(f0)) * 0.01
-    return times, f0, conf
-
-
-def _run(ctx: Ctx) -> None:
-    times, f0, conf = track_pitch(ctx.work / "vocals.wav",
-                                  ctx.cfg.crepe_model, ctx.cfg.device)
-    np.savez(ctx.work / "pitch.npz", times=times, f0=f0, conf=conf)
-
-
-def pitch_stage() -> Stage:
-    return Stage(name="pitch",
-                 outputs=lambda ctx: [ctx.work / "pitch.npz"],
-                 run=_run)

src/karaoke_maker/stages/transcribe.py

@@ -1,43 +0,0 @@
-import difflib
-import json
-
-from ..lyrics import RefLyrics, alignment_token
-from ..pipeline import Ctx, Stage
-from ..whisper_client import TranscriptSegment, transcribe
-
-
-def vocal_sections(segments, min_gap: float = 6.0, pad: float = 1.0):
-    sections = []
-    for s in sorted(segments, key=lambda s: s.start):
-        if sections and s.start - sections[-1][1] < min_gap:
-            sections[-1][1] = max(sections[-1][1], s.end)
-        else:
-            sections.append([s.start, s.end])
-    return [(max(0.0, a - pad), b + pad) for a, b in sections]
-
-
-def _tokens(text: str) -> list[str]:
-    return [t for w in text.split() if (t := alignment_token(w))]
-
-
-def lyrics_similarity(segments, ref: RefLyrics) -> float:
-    heard = [t for s in segments for t in _tokens(s.text)]
-    expected = [t for w in ref.words if (t := alignment_token(w))]
-    return difflib.SequenceMatcher(a=heard, b=expected).ratio()
-
-
-def _run(ctx: Ctx) -> None:
-    segments = transcribe(ctx.cfg, ctx.work / "vocals.wav", ctx.inp.language)
-    (ctx.work / "transcript.json").write_text(json.dumps(
-        [{"start": s.start, "end": s.end, "text": s.text} for s in segments]))
-
-
-def transcribe_stage() -> Stage:
-    return Stage(name="transcribe",
-                 outputs=lambda ctx: [ctx.work / "transcript.json"],
-                 run=_run)
-
-
-def load_transcript(ctx: Ctx) -> list[TranscriptSegment]:
-    data = json.loads((ctx.work / "transcript.json").read_text())
-    return [TranscriptSegment(**d) for d in data]

src/karaoke_maker/static/index.html

@@ -1,982 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<meta name="color-scheme" content="dark">
-<title>karaoke-maker</title>
-<style>
-@font-face {
-  font-family: "Chakra Petch";
-  src: url("/static/fonts/chakra-petch-600.woff2") format("woff2");
-  font-weight: 600; font-display: swap;
-}
-@font-face {
-  font-family: "Chakra Petch";
-  src: url("/static/fonts/chakra-petch-700.woff2") format("woff2");
-  font-weight: 700; font-display: swap;
-}
-
-:root {
-  --bg: #0A0A0F;
-  --panel: #14101F;
-  --panel-raised: #1E1730;
-  --border: #2E2440;
-  --control: #756890;  /* interactive field edges: clears 3:1 on every surface */
-  --text: #F0EDF7;
-  --text-muted: #9B92AD;
-  --purple: #A855F7;
-  --aqua: #22D3EE;
-  --warn: #FBBF24;
-  --fail: #FB5E7E;
-  --done: #C4A5F5;
-
-  --font-display: "Chakra Petch", system-ui, sans-serif;
-  --font-body: system-ui, -apple-system, "Segoe UI", sans-serif;
-  --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
-}
-
-*, *::before, *::after { box-sizing: border-box; }
-
-body {
-  margin: 0;
-  height: 100vh;
-  height: 100dvh;
-  overflow: hidden;
-  display: grid;
-  grid-template-columns: 260px 1fr;
-  grid-template-rows: 1fr auto;
-  grid-template-areas: "sidebar main" "now now";
-  background: var(--bg);
-  color: var(--text);
-  font-family: var(--font-body);
-  font-size: 15px;
-  line-height: 1.5;
-}
-
-:focus-visible { outline: 2px solid var(--aqua); outline-offset: 2px; }
-
-.eyebrow {
-  margin: 0;
-  font-family: var(--font-display);
-  font-weight: 700;
-  font-size: 0.68rem;
-  letter-spacing: 0.2em;
-  text-transform: uppercase;
-  color: var(--text-muted);
-}
-
-.empty-note { margin: 0; font-size: 0.82rem; color: var(--text-muted); }
-
-.sr-only {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  overflow: hidden;
-  clip-path: inset(50%);
-  white-space: nowrap;
-}
-
-/* --- sidebar ------------------------------------------------------------ */
-
-#sidebar {
-  grid-area: sidebar;
-  overflow-y: auto;
-  padding: 24px 0 28px;
-  background: var(--panel);
-  border-right: 1px solid var(--border);
-  display: flex;
-  flex-direction: column;
-  gap: 22px;
-}
-
-.brand { padding: 0 18px; }
-
-.wordmark {
-  margin: 0;
-  font-family: var(--font-display);
-  font-weight: 700;
-  font-size: 1.15rem;
-  line-height: 0.98;
-  letter-spacing: 0.2em;
-}
-.wordmark span { display: block; }
-.wordmark .second { color: var(--purple); }
-
-.kana {
-  margin-top: 9px;
-  font-size: 0.72rem;
-  letter-spacing: 0.4em;
-  color: var(--purple);
-}
-
-#sidebar .eyebrow, #jobs .empty-note { padding: 0 18px; }
-
-#jobs { display: flex; flex-direction: column; gap: 1px; margin-top: 8px; }
-
-.job {
-  position: relative;
-  display: grid;
-  grid-template-columns: 1fr auto;
-  gap: 1px 10px;
-  width: 100%;
-  padding: 10px 16px 11px 15px;
-  border: 0;
-  border-left: 3px solid var(--border);
-  border-radius: 0;
-  background: var(--panel);
-  color: inherit;
-  font: inherit;
-  text-align: left;
-  cursor: pointer;
-  transition: background 120ms ease;
-}
-/* inset so the sidebar's scroll container cannot clip the left edge */
-.job:focus-visible { outline-offset: -2px; }
-.job:hover { background: var(--panel-raised); }
-.job[aria-current="true"] { background: var(--panel-raised); }
-.job[aria-current="true"]::after {
-  content: "";
-  position: absolute;
-  inset: 0 0 0 auto;
-  width: 2px;
-  background: var(--purple);
-}
-
-.job-title {
-  grid-area: 1 / 1;
-  font-family: var(--font-display);
-  font-weight: 600;
-  font-size: 0.9rem;
-  letter-spacing: 0.01em;
-}
-.job-artist { grid-area: 2 / 1; font-size: 0.78rem; color: var(--text-muted); }
-.job-title, .job-artist { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-
-.job-state {
-  grid-area: 3 / 1;
-  margin-top: 4px;
-  display: flex;
-  align-items: baseline;
-  gap: 7px;
-  font-size: 0.72rem;
-  color: var(--text-muted);
-}
-.job-glyph { font-size: 0.8rem; }
-.job-elapsed {
-  grid-area: 3 / 2;
-  align-self: end;
-  font-family: var(--font-mono);
-  font-size: 0.7rem;
-  color: var(--text-muted);
-}
-
-.st-queued { border-left-color: var(--control); }
-.st-queued .job-glyph { color: var(--text-muted); }
-.st-running { border-left-color: var(--aqua); box-shadow: inset 7px 0 14px -7px var(--aqua); }
-.st-running .job-glyph, .st-running .job-state { color: var(--aqua); }
-.st-done { border-left-color: var(--done); }
-.st-done .job-glyph { color: var(--done); }
-.st-failed { border-left-color: var(--fail); }
-.st-failed .job-glyph, .st-failed .job-state { color: var(--fail); }
-
-/* --- main --------------------------------------------------------------- */
-
-#main { grid-area: main; overflow-y: auto; padding: 30px 34px 36px; }
-#main > section { max-width: 760px; margin-inline: auto; }
-#main h2 {
-  margin: 0 0 18px;
-  font-family: var(--font-display);
-  font-weight: 700;
-  font-size: 0.8rem;
-  letter-spacing: 0.22em;
-  color: var(--text-muted);
-}
-
-#song-form { display: grid; gap: 18px; }
-.pair { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
-.field { display: flex; flex-direction: column; gap: 6px; }
-.field > span {
-  font-family: var(--font-display);
-  font-weight: 600;
-  font-size: 0.68rem;
-  letter-spacing: 0.14em;
-  text-transform: uppercase;
-  color: var(--text-muted);
-}
-
-input, textarea {
-  font-family: var(--font-body);
-  font-size: 0.95rem;
-  color: var(--text);
-  background: transparent;
-  border: 0;
-  border-bottom: 1px solid var(--control);
-  border-radius: 0;
-  padding: 7px 2px;
-  transition: border-color 120ms ease;
-}
-input:not([type="file"]):hover { border-bottom-color: var(--text-muted); }
-input:not([type="file"]):focus { border-bottom-color: var(--aqua); }
-
-textarea {
-  min-height: 8.5rem;
-  padding: 11px 13px;
-  line-height: 1.6;
-  background: var(--panel);
-  border: 1px solid var(--control);
-  resize: vertical;
-}
-textarea:hover { border-color: var(--text-muted); }
-textarea:focus { border-color: var(--aqua); }
-
-input[type="file"] {
-  font-size: 0.82rem;
-  color: var(--text-muted);
-  padding: 10px;
-  background: var(--panel);
-  border: 1px dashed var(--control);
-}
-input[type="file"]:hover { border-color: var(--text-muted); }
-.field.dropping input[type="file"] {
-  color: var(--text);
-  background: var(--panel-raised);
-  border-color: var(--aqua);
-}
-input[type="file"]::file-selector-button {
-  margin-right: 11px;
-  padding: 6px 11px;
-  font-family: var(--font-display);
-  font-weight: 600;
-  font-size: 0.68rem;
-  letter-spacing: 0.1em;
-  text-transform: uppercase;
-  color: var(--text);
-  background: var(--panel-raised);
-  border: 1px solid var(--control);
-  border-radius: 2px;
-  cursor: pointer;
-}
-
-details { border-top: 1px solid var(--border); padding-top: 15px; }
-summary {
-  display: flex;
-  align-items: center;
-  gap: 9px;
-  font-family: var(--font-display);
-  font-weight: 700;
-  font-size: 0.68rem;
-  letter-spacing: 0.18em;
-  text-transform: uppercase;
-  color: var(--text-muted);
-  cursor: pointer;
-  list-style: none;
-}
-summary::-webkit-details-marker { display: none; }
-/* the second `content` keeps the marker out of the accessible name; browsers
-   without alt-text support drop it and fall back to the plain marker */
-summary::before {
-  content: "+";
-  content: "+" / "";
-  font-family: var(--font-mono);
-  color: var(--aqua);
-}
-details[open] > summary::before {
-  content: "\2212";
-  content: "\2212" / "";
-}
-summary:hover { color: var(--text); }
-details > .stack { display: grid; gap: 18px; margin-top: 18px; }
-
-button { cursor: pointer; }
-.primary {
-  justify-self: start;
-  padding: 12px 24px;
-  font-family: var(--font-display);
-  font-weight: 700;
-  font-size: 0.75rem;
-  letter-spacing: 0.16em;
-  text-transform: uppercase;
-  color: #12061F;
-  background: var(--purple);
-  border: 0;
-  border-radius: 2px;
-  transition: background 120ms ease;
-}
-.primary:hover { background: #BE7BF9; }
-
-#form-error { margin: 12px 0 0; min-height: 1.2em; font-size: 0.85rem; color: var(--fail); }
-
-#review { margin-top: 38px; }
-#review h3 {
-  margin: -8px 0 16px;
-  font-family: var(--font-display);
-  font-weight: 600;
-  font-size: 1rem;
-}
-#review h3 span { color: var(--text-muted); font-weight: 400; }
-
-#warnings { display: flex; flex-direction: column; gap: 1px; }
-.warn-row {
-  display: grid;
-  grid-template-columns: auto auto 1fr;
-  align-items: center;
-  gap: 10px;
-  padding: 10px 12px;
-  background: var(--panel);
-  border: 1px solid var(--border);
-}
-.warn-row + .warn-row { margin-top: 6px; }
-.warn-icon { color: var(--warn); }
-.warn-count { font-size: 0.85rem; }
-.warn-range { justify-self: end; font-family: var(--font-mono); font-size: 0.82rem; color: var(--text-muted); }
-
-.review-error { margin: 0 0 14px; font-size: 0.85rem; color: var(--fail); }
-
-.output-path {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  margin: 14px 0 0;
-  padding: 10px 12px;
-  background: var(--panel);
-  border: 1px solid var(--border);
-}
-.output-path code { flex: 1; overflow-wrap: anywhere; font-family: var(--font-mono); font-size: 0.82rem; }
-#copy-path, .action, #cancel-rebuild {
-  flex: none;
-  padding: 5px 12px;
-  font-family: var(--font-display);
-  font-weight: 600;
-  font-size: 0.68rem;
-  letter-spacing: 0.1em;
-  text-transform: uppercase;
-  color: var(--text);
-  background: var(--panel-raised);
-  border: 1px solid var(--control);
-  border-radius: 2px;
-}
-#copy-path:hover, .action:hover, #cancel-rebuild:hover { border-color: var(--text-muted); }
-
-.form-actions { display: flex; align-items: center; gap: 14px; }
-.keep-note { margin: -8px 0 0; font-size: 0.78rem; color: var(--aqua); }
-#review-actions { display: flex; gap: 10px; margin-top: 14px; }
-#review-lineage { margin: -10px 0 14px; }
-.lineage {
-  padding: 0;
-  font: inherit;
-  font-size: 0.8rem;
-  color: var(--aqua);
-  background: none;
-  border: 0;
-  border-bottom: 1px solid transparent;
-}
-.lineage:hover { border-bottom-color: var(--aqua); }
-.job-mark { grid-area: 1 / 2; justify-self: end; font-size: 0.8rem; color: var(--text-muted); }
-
-#detail {
-  margin: 13px 0 0;
-  padding: 14px;
-  max-height: 20rem;
-  overflow-y: auto;
-  white-space: pre-wrap;
-  font-family: var(--font-mono);
-  font-size: 0.78rem;
-  line-height: 1.65;
-  color: var(--text-muted);
-  background: var(--panel);
-  border: 1px solid var(--border);
-}
-
-/* --- now bar ------------------------------------------------------------ */
-
-#now-bar {
-  grid-area: now;
-  display: flex;
-  align-items: center;
-  gap: 18px;
-  padding: 13px 20px;
-  background: var(--panel);
-  border-top: 1px solid var(--border);
-}
-#now-label {
-  flex: none;
-  font-family: var(--font-display);
-  font-weight: 700;
-  font-size: 0.62rem;
-  letter-spacing: 0.22em;
-  color: var(--text-muted);
-}
-#now-title {
-  font-family: var(--font-display);
-  font-weight: 600;
-  font-size: 0.9rem;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-#now-bar.idle #now-title { color: var(--text-muted); font-weight: 400; font-family: var(--font-body); font-size: 0.82rem; }
-#stage-track { display: flex; align-items: center; gap: 15px; margin-left: auto; }
-
-.stage { display: flex; align-items: baseline; gap: 6px; color: var(--text-muted); }
-.stage-dot { font-size: 0.72rem; }
-.stage-label {
-  font-family: var(--font-display);
-  font-weight: 600;
-  font-size: 0.62rem;
-  letter-spacing: 0.12em;
-  text-transform: uppercase;
-}
-.stage-done { color: var(--done); }
-.stage-active { color: var(--aqua); }
-@keyframes stage-pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.45; } }
-.stage-active .stage-dot { color: var(--aqua); animation: stage-pulse 1.6s ease-in-out infinite; }
-
-.stage-counter {
-  padding-left: 3px;
-  font-family: var(--font-mono);
-  font-size: 0.72rem;
-  color: var(--text-muted);
-}
-
-@media (max-width: 1180px) {
-  #stage-track { gap: 11px; }
-  /* clipped rather than display:none so the names stay in the accessibility tree */
-  .stage:not(.stage-active) .stage-label { position: absolute; clip-path: inset(50%); }
-}
-
-/* --- responsive --------------------------------------------------------- */
-
-@media (max-width: 900px) {
-  body {
-    grid-template-columns: 1fr;
-    grid-template-rows: auto minmax(0, 1fr) auto;
-    grid-template-areas: "sidebar" "main" "now";
-  }
-  #sidebar {
-    max-height: 42vh;
-    border-right: 0;
-    border-bottom: 1px solid var(--border);
-  }
-  #main { padding: 24px 18px 28px; }
-  .pair { grid-template-columns: 1fr; }
-  #now-bar { flex-wrap: wrap; gap: 8px 16px; }
-  #stage-track { margin-left: 0; flex-wrap: wrap; }
-}
-
-@media (prefers-reduced-motion: reduce) {
-  *, *::before, *::after { animation: none !important; transition: none !important; }
-}
-</style>
-</head>
-<body>
-
-<aside id="sidebar">
-  <div class="brand">
-    <h1 class="wordmark"><span>KARAOKE</span> <span class="second">MAKER</span></h1>
-    <div class="kana" aria-hidden="true">カラオケ</div>
-  </div>
-  <div>
-    <h2 class="eyebrow">QUEUE</h2>
-    <div id="jobs"></div>
-  </div>
-</aside>
-
-<main id="main">
-  <section id="new-song">
-    <h2>NEW SONG</h2>
-    <form id="song-form">
-      <div class="pair">
-        <label class="field"><span>Title</span><input name="title" required></label>
-        <label class="field"><span>Artist</span><input name="artist" required></label>
-      </div>
-      <label class="field"><span>Lyrics</span><textarea name="lyrics" required></textarea></label>
-      <details>
-        <summary>Advanced</summary>
-        <div class="stack">
-          <label class="field"><span>YouTube URL</span><input name="youtube_url"></label>
-          <label class="field"><span>Video file</span><input type="file" name="video"></label>
-          <p class="keep-note" data-keep="video" hidden></p>
-          <div class="pair">
-            <label class="field"><span>Genre</span><input name="genre"></label>
-            <label class="field"><span>Year</span><input name="year" type="number"></label>
-          </div>
-          <div class="pair">
-            <label class="field"><span>Language</span><input name="language"></label>
-            <label class="field"><span>BPM override</span><input name="bpm" type="number" step="any"></label>
-          </div>
-          <label class="field"><span>Cover image</span><input type="file" name="cover"></label>
-          <p class="keep-note" data-keep="cover" hidden></p>
-        </div>
-      </details>
-      <div class="form-actions">
-        <button type="submit" class="primary">CREATE SONG</button>
-        <button type="button" id="cancel-rebuild" hidden>CANCEL</button>
-      </div>
-    </form>
-    <p id="form-error" role="alert"></p>
-  </section>
-
-  <section id="review">
-    <h2>REVIEW</h2>
-    <h3 id="review-title"></h3>
-    <p id="review-lineage" hidden></p>
-    <p id="review-error" class="review-error" hidden></p>
-    <div id="warnings"><p class="empty-note">no songs queued yet — nothing to review</p></div>
-    <div id="output-path"></div>
-    <div id="review-actions"></div>
-    <details>
-      <summary>Log</summary>
-      <pre id="detail">no songs queued yet — nothing to log</pre>
-    </details>
-  </section>
-</main>
-
-<footer id="now-bar" class="idle">
-  <span id="now-label">IDLE</span>
-  <span id="now-title">nothing in progress</span>
-  <div id="stage-track"></div>
-</footer>
-
-<script>
-const form = document.getElementById("song-form");
-const formError = document.getElementById("form-error");
-const jobsDiv = document.getElementById("jobs");
-const detail = document.getElementById("detail");
-const reviewTitle = document.getElementById("review-title");
-const reviewError = document.getElementById("review-error");
-const outputPathDiv = document.getElementById("output-path");
-const nowBar = document.getElementById("now-bar");
-const nowLabel = document.getElementById("now-label");
-const nowTitle = document.getElementById("now-title");
-const stageTrack = document.getElementById("stage-track");
-const reviewActions = document.getElementById("review-actions");
-const reviewLineage = document.getElementById("review-lineage");
-const cancelRebuild = document.getElementById("cancel-rebuild");
-const formHeading = document.querySelector("#new-song h2");
-const submitButton = form.querySelector("button[type=submit]");
-let rebuildOf = null;
-let JOBS = [];
-let selectedId = null;
-let STAGES = [];
-let pollTimer = null;
-
-const WARN_RE = /^(\d+)\s+low-confidence notes?\s+near\s+(\d+:\d{2})–(\d+:\d{2})/;
-
-const STATE = {
-  queued:  { glyph: "○", cls: "st-queued"  },
-  running: { glyph: "◈", cls: "st-running" },
-  done:    { glyph: "●", cls: "st-done"    },
-  failed:  { glyph: "✕", cls: "st-failed"  },
-};
-
-function elapsed(job) {
-  if (!job.started_at) return "";
-  const end = job.finished_at ?? Date.now() / 1000;
-  const secs = Math.max(0, Math.round(end - job.started_at));
-  const m = Math.floor(secs / 60), s = secs % 60;
-  return m ? `${m}m${String(s).padStart(2, "0")}s` : `${s}s`;
-}
-
-form.addEventListener("submit", async (e) => {
-  e.preventDefault();
-  formError.textContent = "";
-  const data = new FormData(form);
-  for (const [name, value] of [...data.entries()]) {
-    const isFile = value instanceof File;
-    if (isFile && value.size === 0) data.delete(name);
-    else if (!isFile && value === "") data.delete(name);
-  }
-  const url = rebuildOf ? `/api/jobs/${rebuildOf}/rebuild` : "/api/jobs";
-  const resp = await fetch(url, { method: "POST", body: data });
-  if (!resp.ok) {
-    const body = await resp.json().catch(() => ({}));
-    formError.textContent = body.detail || `error: ${resp.status}`;
-    return;  // before the reset below, so a rejected submission is never retyped
-  }
-  selectedId = (await resp.json()).id;
-  exitRebuild();
-  refreshJobs();
-});
-
-for (const input of form.querySelectorAll('input[type="file"]')) {
-  const zone = input.closest(".field");
-  zone.addEventListener("dragover", (e) => {
-    e.preventDefault();
-    zone.classList.add("dropping");
-  });
-  zone.addEventListener("dragleave", (e) => {
-    if (!zone.contains(e.relatedTarget)) zone.classList.remove("dropping");
-  });
-  zone.addEventListener("drop", (e) => {
-    e.preventDefault();
-    zone.classList.remove("dropping");
-    const [file] = e.dataTransfer.files;
-    if (!file) return;
-    // a single-file input needs a one-item FileList, which only DataTransfer can build
-    const picked = new DataTransfer();
-    picked.items.add(file);
-    input.files = picked.files;
-  });
-}
-
-cancelRebuild.addEventListener("click", exitRebuild);
-
-function jobCard(job) {
-  const card = document.createElement("button");
-  card.type = "button";
-  card.dataset.id = job.id;
-
-  const title = document.createElement("span");
-  title.className = "job-title";
-
-  const artist = document.createElement("span");
-  artist.className = "job-artist";
-
-  const glyph = document.createElement("span");
-  glyph.className = "job-glyph";
-  glyph.setAttribute("aria-hidden", "true");
-  const status = document.createElement("span");
-  const stateLine = document.createElement("span");
-  stateLine.className = "job-state";
-  stateLine.append(glyph, status);
-
-  const time = document.createElement("span");
-  time.className = "job-elapsed";
-
-  const mark = document.createElement("span");
-  mark.className = "job-mark";
-  const markGlyph = document.createElement("span");
-  markGlyph.setAttribute("aria-hidden", "true");
-  const markLabel = document.createElement("span");
-  markLabel.className = "sr-only";
-  mark.append(markGlyph, markLabel);
-
-  card.append(title, artist, stateLine, time, mark);
-  card.addEventListener("click", () => selectJob(job.id));
-  paintCard(card, job);
-  return card;
-}
-
-function paintCard(card, job) {
-  const state = STATE[job.status] ?? { glyph: "·", cls: "st-queued" };
-  const [title, artist, stateLine, time, mark] = card.children;
-  card.className = `job ${state.cls}`;
-  if (job.id === selectedId) card.setAttribute("aria-current", "true");
-  else card.removeAttribute("aria-current");
-  title.textContent = job.title;
-  artist.textContent = job.artist;
-  stateLine.children[0].textContent = state.glyph;
-  stateLine.children[1].textContent = job.stage ? `${job.status} · ${job.stage}` : job.status;
-  time.textContent = elapsed(job);
-  mark.children[0].textContent = job.rebuilt_from ? "↻" : "";
-  mark.children[1].textContent = job.rebuilt_from ? " rebuilt" : "";
-}
-
-// patched in place rather than replaced wholesale: detaching a card would blur
-// it, so a keyboard user would lose the queue on every poll
-function renderJobs(jobs) {
-  if (!jobs.length) {
-    jobsDiv.replaceChildren(emptyNote("no songs yet — create one to get started"));
-    return;
-  }
-  const existing = new Map(
-    [...jobsDiv.querySelectorAll(".job")].map(card => [card.dataset.id, card]));
-  jobs.forEach((job, i) => {
-    let card = existing.get(job.id);
-    if (card) { existing.delete(job.id); paintCard(card, job); }
-    else card = jobCard(job);
-    if (jobsDiv.children[i] !== card) jobsDiv.insertBefore(card, jobsDiv.children[i] ?? null);
-  });
-  for (const stale of existing.values()) stale.remove();
-  while (jobsDiv.children.length > jobs.length) jobsDiv.lastElementChild.remove();
-}
-
-async function loadStages() {
-  const resp = await fetch("/api/stages");
-  STAGES = (await resp.json()).stages;
-}
-
-function renderStageTrack(job) {
-  if (!STAGES.length || !job || job.status === "queued") {
-    stageTrack.replaceChildren();
-    return;
-  }
-  const idx = job.stage ? STAGES.indexOf(job.stage) : -1;
-  const dots = STAGES.map((name, i) => {
-    const done = job.status === "done" || i < idx;
-    const active = !done && i === idx;
-    const dot = document.createElement("span");
-    dot.className = "stage " + (done ? "stage-done" : active ? "stage-active" : "stage-pending");
-    if (active) dot.setAttribute("aria-current", "step");
-    const mark = document.createElement("span");
-    mark.className = "stage-dot";
-    mark.setAttribute("aria-hidden", "true");
-    mark.textContent = done ? "●" : active ? "◈" : "○";
-    const label = document.createElement("span");
-    label.className = "stage-label";
-    label.textContent = name;
-    // colour and glyph alone must never carry state
-    const word = document.createElement("span");
-    word.className = "sr-only";
-    word.textContent = done ? " done" : active ? " running" : " pending";
-    dot.append(mark, label, word);
-    return dot;
-  });
-  const counter = document.createElement("span");
-  counter.className = "stage-counter";
-  // an unrecognised stage name gives idx === -1, which reads as 0 done
-  counter.textContent = job.status === "done"
-    ? `${STAGES.length}/${STAGES.length}`
-    : `${Math.max(0, idx + 1)}/${STAGES.length}`;
-  stageTrack.replaceChildren(...dots, counter);
-}
-
-function renderNowBar(jobs) {
-  const running = jobs.find(j => j.status === "running");
-  nowBar.classList.toggle("idle", !running);
-  nowLabel.textContent = running ? "NOW RUNNING" : "IDLE";
-  nowTitle.textContent = running ? `${running.title} · ${running.artist}` : "nothing in progress";
-  renderStageTrack(running);
-}
-
-function schedulePoll(jobs) {
-  const busy = jobs.some(j => j.status === "queued" || j.status === "running");
-  if (busy && pollTimer === null) {
-    pollTimer = setInterval(refreshJobs, 3000);
-  } else if (!busy && pollTimer !== null) {
-    clearInterval(pollTimer);
-    pollTimer = null;
-  }
-}
-
-async function refreshJobs() {
-  const resp = await fetch("/api/jobs");
-  const jobs = await resp.json();
-  JOBS = jobs;
-  if (selectedId === null && jobs.length) selectedId = jobs[0].id;
-  renderJobs(jobs);
-  renderNowBar(jobs);
-  if (selectedId) refreshDetail();
-  schedulePoll(jobs);
-}
-
-async function selectJob(id) {
-  selectedId = id;
-  for (const card of jobsDiv.querySelectorAll(".job")) {
-    if (card.dataset.id === id) card.setAttribute("aria-current", "true");
-    else card.removeAttribute("aria-current");
-  }
-  refreshDetail();
-}
-
-function emptyNote(text) {
-  const p = document.createElement("p");
-  p.className = "empty-note";
-  p.textContent = text;
-  return p;
-}
-
-function renderWarnings(job) {
-  const box = document.getElementById("warnings");
-  if (job.status === "failed") {
-    box.replaceChildren(emptyNote("job failed — nothing to review"));
-    return;
-  }
-  if (job.status !== "done") {
-    box.replaceChildren(emptyNote("waiting for this song to finish…"));
-    return;
-  }
-  if (!job.warnings.length) {
-    box.replaceChildren(emptyNote("no low-confidence regions — nothing to review"));
-    return;
-  }
-  const rows = job.warnings.map(w => {
-    const m = WARN_RE.exec(w);
-    const row = document.createElement("div");
-    row.className = "warn-row";
-    if (m) {
-      row.setAttribute("data-count", m[1]);
-      row.setAttribute("data-start", m[2]);
-      row.setAttribute("data-end", m[3]);
-      const icon = document.createElement("span");
-      icon.className = "warn-icon";
-      icon.textContent = "⚠";
-      const count = document.createElement("span");
-      count.className = "warn-count";
-      count.textContent = `${m[1]} note${m[1] === "1" ? "" : "s"}`;
-      const range = document.createElement("span");
-      range.className = "warn-range";
-      range.textContent = `${m[2]}–${m[3]}`;
-      row.append(icon, count, range);
-    } else {
-      row.textContent = w;
-    }
-    return row;
-  });
-  box.replaceChildren(...rows);
-}
-
-async function copyPath(path, button) {
-  let ok = false;
-  if (navigator.clipboard) {
-    try {
-      await navigator.clipboard.writeText(path);
-      ok = true;
-    } catch {}
-  }
-  // navigator.clipboard is undefined outside secure contexts, which is the
-  // normal case for this intranet tool served over plain http
-  if (!ok) {
-    const ta = document.createElement("textarea");
-    ta.value = path;
-    ta.style.position = "fixed";
-    ta.style.left = "-1000px";
-    document.body.appendChild(ta);
-    ta.focus();
-    ta.select();
-    try { ok = document.execCommand("copy"); } catch { ok = false; }
-    document.body.removeChild(ta);
-  }
-  if (!ok) {
-    const code = outputPathDiv.querySelector("code");
-    if (code) {
-      const range = document.createRange();
-      range.selectNodeContents(code);
-      const sel = window.getSelection();
-      sel.removeAllRanges();
-      sel.addRange(range);
-    }
-  }
-  button.textContent = ok ? "copied" : "copy failed";
-  setTimeout(() => { button.textContent = "copy"; }, 1500);
-}
-
-function renderOutputPath(job) {
-  const path = job.status === "done" ? job.output_dir ?? null : null;
-  const shown = outputPathDiv.querySelector("code")?.textContent ?? null;
-  // rebuilding an unchanged panel would detach a focused #copy-path on every poll
-  if (path === shown) return;
-  if (path === null) {
-    outputPathDiv.replaceChildren();
-    return;
-  }
-  const wrap = document.createElement("div");
-  wrap.className = "output-path";
-  const code = document.createElement("code");
-  code.textContent = path;
-  const button = document.createElement("button");
-  button.id = "copy-path";
-  button.type = "button";
-  button.textContent = "copy";
-  button.addEventListener("click", () => copyPath(path, button));
-  wrap.append(code, button);
-  outputPathDiv.replaceChildren(wrap);
-}
-
-function setFormMode(inp) {
-  formHeading.textContent = rebuildOf ? "REBUILD" : "NEW SONG";
-  submitButton.textContent = rebuildOf ? "REBUILD SONG" : "CREATE SONG";
-  cancelRebuild.hidden = !rebuildOf;
-  for (const [field, key] of [["video", "video_filename"], ["cover", "cover_filename"]]) {
-    const note = form.querySelector(`[data-keep="${field}"]`);
-    const kept = rebuildOf && inp ? inp[key] : null;
-    note.textContent = kept ? `keeping ${kept} — attach a file to replace it` : "";
-    note.hidden = !kept;
-  }
-}
-
-function exitRebuild() {
-  rebuildOf = null;
-  form.reset();
-  setFormMode(null);
-}
-
-async function startRebuild(id) {
-  const resp = await fetch(`/api/jobs/${id}/input`);
-  if (!resp.ok) return;
-  const inp = await resp.json();
-  form.reset();
-  for (const [name, value] of Object.entries(inp)) {
-    // the payload is keyed by form field name; *_filename match nothing, by design
-    const el = form.elements[name];
-    if (el && value !== null) el.value = value;
-  }
-  rebuildOf = id;
-  setFormMode(inp);
-  formError.textContent = "";
-  form.elements.title.focus();
-}
-
-async function rerunJob(id) {
-  formError.textContent = "";
-  const resp = await fetch(`/api/jobs/${id}/rerun`, { method: "POST" });
-  if (!resp.ok) {
-    const body = await resp.json().catch(() => ({}));
-    formError.textContent = body.detail || `error: ${resp.status}`;
-    return;
-  }
-  selectedId = (await resp.json()).id;
-  refreshJobs();
-}
-
-function actionButton(action, jobId) {
-  const button = document.createElement("button");
-  button.type = "button";
-  button.className = "action";
-  button.dataset.action = action;
-  button.textContent = action === "rerun" ? "RERUN" : "EDIT & REBUILD";
-  button.addEventListener("click",
-    () => action === "rerun" ? rerunJob(jobId) : startRebuild(jobId));
-  return button;
-}
-
-function renderActions(job) {
-  // no controls mid-run: both endpoints answer 409 until the job settles
-  const wanted = job.status === "failed" ? ["rerun", "edit"]
-               : job.status === "done" ? ["edit"] : [];
-  const shown = [...reviewActions.children].map(b => b.dataset.action);
-  // rebuilding an unchanged row would detach a focused action on every poll
-  if (reviewActions.dataset.jobId === job.id && shown.join() === wanted.join()) return;
-  reviewActions.dataset.jobId = job.id;
-  reviewActions.replaceChildren(...wanted.map(a => actionButton(a, job.id)));
-}
-
-function renderLineage(job) {
-  if (reviewLineage.dataset.jobId === job.id) return;
-  reviewLineage.dataset.jobId = job.id;
-  reviewLineage.replaceChildren();
-  reviewLineage.hidden = !job.rebuilt_from;
-  if (!job.rebuilt_from) return;
-  const parent = JOBS.find(j => j.id === job.rebuilt_from);
-  const link = document.createElement("button");
-  link.type = "button";
-  link.className = "lineage";
-  link.textContent = parent ? `rebuilt from ${parent.title}`
-                            : "rebuilt from an earlier run";
-  link.addEventListener("click", () => selectJob(job.rebuilt_from));
-  reviewLineage.append(link);
-}
-
-async function refreshDetail() {
-  const id = selectedId;
-  const resp = await fetch(`/api/jobs/${id}`);
-  if (!resp.ok) return;
-  const job = await resp.json();
-  if (id !== selectedId) return;
-  const artist = document.createElement("span");
-  artist.textContent = job.artist;
-  reviewTitle.replaceChildren(`${job.title} `, artist);
-  reviewError.hidden = !job.error;
-  reviewError.textContent = job.error ?? "";
-  renderWarnings(job);
-  renderOutputPath(job);
-  renderLineage(job);
-  renderActions(job);
-  detail.textContent = job.log.join("\n");
-}
-
-loadStages().catch(() => {}).then(refreshJobs);
-</script>
-</body>
-</html>

src/karaoke_maker/web.py

@@ -1,312 +0,0 @@
-import math
-import queue
-import re
-import shutil
-import threading
-import time
-import uuid
-from dataclasses import dataclass, field
-from pathlib import Path
-
-from fastapi import FastAPI, File, Form, HTTPException, UploadFile
-from fastapi.concurrency import run_in_threadpool
-from fastapi.responses import FileResponse
-from fastapi.staticfiles import StaticFiles
-
-from . import rebuild as rebuild_policy
-from .config import Config
-from .pipeline import (STAGE_ORDER, PipelineError, SongInput, run_pipeline,
-                       song_slug)
-
-STATIC = Path(__file__).parent / "static"
-STAGE_LINE = re.compile(r"^\[(\w+)\] (?:running|cached, skipping)")
-
-
-@dataclass
-class Job:
-    id: str
-    title: str
-    artist: str
-    status: str = "queued"
-    stage: str | None = None
-    log: list[str] = field(default_factory=list)
-    output_dir: str | None = None
-    warnings: list[str] = field(default_factory=list)
-    error: str | None = None
-    inp: SongInput | None = None
-    rebuilt_from: str | None = None
-    created_at: float = field(default_factory=time.time)
-    started_at: float | None = None
-    finished_at: float | None = None
-
-
-def _safe_filename(name: str | None, default: str) -> str:
-    safe = Path(name).name if name else ""
-    return safe if safe not in ("", ".", "..") else default
-
-
-async def _save_upload(upload: UploadFile, dest: Path) -> None:
-    with dest.open("wb") as f:
-        await run_in_threadpool(shutil.copyfileobj, upload.file, f)
-
-
-async def _store_uploads(cfg: Config, job_id: str, video: UploadFile | None,
-                         cover: UploadFile | None) -> tuple[Path | None, Path | None]:
-    updir = cfg.work_dir / "uploads" / job_id
-    paths = []
-    for upload, default in ((video, "video"), (cover, "cover")):
-        if not (upload and upload.filename):
-            paths.append(None)
-            continue
-        updir.mkdir(parents=True, exist_ok=True)
-        dest = updir / _safe_filename(upload.filename, default)
-        await _save_upload(upload, dest)
-        paths.append(dest)
-    return paths[0], paths[1]
-
-
-def _cleanup_uploads(cfg: Config, job_id: str, video_path: Path | None) -> None:
-    """Drop the video upload a finished job no longer needs.
-
-    Covers are left behind: they are small, and a rebuild inherits cover_path, so
-    removing one would silently strip #COVER from the rebuilt song. A rebuild can
-    also inherit its parent's upload, so the directory is not always uploads/<job_id>.
-    Never raises — the caller has already marked the job done.
-    """
-    uploads = (cfg.work_dir / "uploads").resolve()
-    dirs = {uploads / job_id}
-    if video_path is not None:
-        target = Path(video_path)
-        parent = target.resolve().parent
-        if parent.parent == uploads:
-            try:
-                target.unlink(missing_ok=True)
-            except OSError:
-                pass
-            dirs.add(parent)
-    for d in dirs:
-        try:
-            d.rmdir()
-        except OSError:
-            pass
-
-
-def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
-    app = FastAPI()
-    app.mount("/static", StaticFiles(directory=STATIC), name="static")
-    jobs: dict[str, Job] = {}
-    order: list[str] = []
-    lock = threading.Lock()
-    todo: queue.Queue[str] = queue.Queue()
-
-    def _prepare_rebuild(job: Job, log) -> str | None:
-        """Relocate cached work and report the stage this rebuild restarts from."""
-        if not job.rebuilt_from:
-            return None
-        with lock:
-            parent = jobs.get(job.rebuilt_from)
-        if parent is None:
-            return None
-        force_from = rebuild_policy.plan(parent.inp, job.inp)
-        changed = rebuild_policy.changed_fields(parent.inp, job.inp)
-        rebuild_policy.relocate_work(parent.inp, job.inp, cfg)
-        log(f"[rebuild] restarting from {force_from or 'the first incomplete stage'}"
-            f" ({', '.join(changed) if changed else 'nothing'} changed)")
-        return force_from
-
-    def _drop_superseded_output(job: Job, log) -> None:
-        if not job.rebuilt_from:
-            return
-        with lock:
-            parent = jobs.get(job.rebuilt_from)
-        if parent is None or parent.status != "done":
-            return
-        old = rebuild_policy.superseded_output(parent.output_dir, job.output_dir,
-                                                cfg.output_dir)
-        if old is None:
-            return
-        shutil.rmtree(old, ignore_errors=True)
-        log(f"[rebuild] removed superseded {old.name}")
-
-    def worker():
-        while True:
-            job_id = todo.get()
-            with lock:
-                job = jobs[job_id]
-                job.status = "running"
-                job.started_at = time.time()
-
-            def log(msg: str, job=job):
-                with lock:
-                    job.log.append(msg)
-                    if m := STAGE_LINE.match(msg):
-                        job.stage = m[1]
-
-            try:
-                force_from = _prepare_rebuild(job, log)
-                result = runner(job.inp, cfg, log=log, force_from=force_from)
-                with lock:
-                    job.output_dir = str(result.output_dir)
-                    job.warnings = list(result.warnings)
-                _drop_superseded_output(job, log)
-                with lock:
-                    job.status = "done"
-                # uploads survive a failure so the job stays rerunnable; acquire
-                # has already copied the video into the work dir by now.
-                _cleanup_uploads(cfg, job_id, job.inp.video_path)
-            except BaseException as e:
-                with lock:
-                    job.status = "failed"
-                    job.error = str(e)
-            finally:
-                with lock:
-                    job.finished_at = time.time()
-
-    threading.Thread(target=worker, daemon=True).start()
-
-    def _enqueue(job_id: str, inp: SongInput,
-                 rebuilt_from: str | None = None) -> dict:
-        job = Job(id=job_id, title=inp.title, artist=inp.artist, inp=inp,
-                  rebuilt_from=rebuilt_from)
-        with lock:
-            jobs[job_id] = job
-            order.append(job_id)
-        todo.put(job_id)
-        return {"id": job_id}
-
-    def _finished_job(job_id: str) -> Job:
-        with lock:
-            job = jobs.get(job_id)
-            if job is None:
-                raise HTTPException(404)
-            if job.status in ("queued", "running"):
-                raise HTTPException(409, "job is still in progress")
-            return job
-
-    @app.get("/")
-    def index():
-        return FileResponse(STATIC / "index.html")
-
-    @app.post("/api/jobs", status_code=201)
-    async def submit(title: str = Form(...), artist: str = Form(...),
-                      lyrics: str = Form(...), youtube_url: str | None = Form(None),
-                      genre: str | None = Form(None), year: int | None = Form(None),
-                      language: str | None = Form(None), bpm: float | None = Form(None),
-                      video: UploadFile | None = File(None),
-                      cover: UploadFile | None = File(None)):
-        youtube_url, genre, language = (youtube_url or None, genre or None,
-                                        language or None)
-        has_video = bool(video and video.filename)
-        if bool(youtube_url) == has_video:
-            raise HTTPException(400, "provide exactly one of youtube_url / video")
-        if bpm is not None and (not math.isfinite(bpm) or bpm <= 0):
-            raise HTTPException(400, f"bpm must be a finite value > 0, got {bpm!r}")
-
-        job_id = uuid.uuid4().hex
-        video_path, cover_path = await _store_uploads(cfg, job_id, video, cover)
-
-        inp = SongInput(title=title, artist=artist, lyrics_text=lyrics,
-                         youtube_url=youtube_url, video_path=video_path,
-                         genre=genre, year=year, language=language,
-                         cover_path=cover_path, bpm_override=bpm)
-        return _enqueue(job_id, inp)
-
-    @app.post("/api/jobs/{job_id}/rerun", status_code=201)
-    def rerun(job_id: str):
-        parent = _finished_job(job_id)
-        return _enqueue(uuid.uuid4().hex, parent.inp, rebuilt_from=job_id)
-
-    def _require_source(parent_inp: SongInput, inp: SongInput,
-                        force_from: str | None) -> None:
-        """Refuse a rebuild that will rerun acquire against an upload we no longer have."""
-        if inp.video_path is None or inp.video_path.exists():
-            return
-        if force_from != "acquire":
-            # acquire is cached under the old slug until the worker renames it
-            for slug in {song_slug(parent_inp), song_slug(inp)}:
-                work = cfg.work_dir / slug
-                if (work / "meta.json").exists() and (work / "audio.wav").exists():
-                    return
-        raise HTTPException(400, "the original video upload is no longer available; "
-                                 "attach the video file again")
-
-    @app.post("/api/jobs/{job_id}/rebuild", status_code=201)
-    async def rebuild(job_id: str, title: str = Form(...), artist: str = Form(...),
-                      lyrics: str = Form(...), youtube_url: str | None = Form(None),
-                      genre: str | None = Form(None), year: int | None = Form(None),
-                      language: str | None = Form(None), bpm: float | None = Form(None),
-                      video: UploadFile | None = File(None),
-                      cover: UploadFile | None = File(None)):
-        parent = _finished_job(job_id)
-        # a cleared field arrives as "" from some clients; "" and None must not
-        # look like different inputs to plan()
-        youtube_url, genre, language = (youtube_url or None, genre or None,
-                                        language or None)
-        has_video = bool(video and video.filename)
-        if youtube_url and has_video:
-            raise HTTPException(400, "provide exactly one of youtube_url / video")
-        if bpm is not None and (not math.isfinite(bpm) or bpm <= 0):
-            raise HTTPException(400, f"bpm must be a finite value > 0, got {bpm!r}")
-
-        new_id = uuid.uuid4().hex
-        video_path, cover_path = await _store_uploads(cfg, new_id, video, cover)
-        if not youtube_url and not has_video:
-            youtube_url, video_path = parent.inp.youtube_url, parent.inp.video_path
-        if cover_path is None:
-            cover_path = parent.inp.cover_path
-
-        inp = SongInput(title=title, artist=artist, lyrics_text=lyrics,
-                        youtube_url=youtube_url, video_path=video_path,
-                        genre=genre, year=year, language=language,
-                        cover_path=cover_path, bpm_override=bpm)
-        _require_source(parent.inp, inp, rebuild_policy.plan(parent.inp, inp))
-        return _enqueue(new_id, inp, rebuilt_from=job_id)
-
-    @app.get("/api/stages")
-    def list_stages():
-        return {"stages": list(STAGE_ORDER)}
-
-    @app.get("/api/jobs")
-    def list_jobs():
-        with lock:
-            return [{"id": j.id, "title": j.title, "artist": j.artist,
-                      "status": j.status, "stage": j.stage,
-                      "created_at": j.created_at, "started_at": j.started_at,
-                      "finished_at": j.finished_at, "rebuilt_from": j.rebuilt_from}
-                     for j in (jobs[i] for i in reversed(order))]
-
-    @app.get("/api/jobs/{job_id}")
-    def get_job(job_id: str):
-        with lock:
-            job = jobs.get(job_id)
-            if job is None:
-                raise HTTPException(404)
-            return {"id": job.id, "title": job.title, "artist": job.artist,
-                    "status": job.status, "stage": job.stage,
-                    "log": job.log[-100:], "output_dir": job.output_dir,
-                    "warnings": list(job.warnings), "error": job.error,
-                    "created_at": job.created_at, "started_at": job.started_at,
-                    "finished_at": job.finished_at, "rebuilt_from": job.rebuilt_from}
-
-    @app.get("/api/jobs/{job_id}/input")
-    def get_input(job_id: str):
-        with lock:
-            job = jobs.get(job_id)
-            if job is None:
-                raise HTTPException(404)
-            inp = job.inp
-        # keys are the form's field names so the page can prefill by name;
-        # paths are reduced to filenames, which is all the browser can use.
-        return {"title": inp.title, "artist": inp.artist, "lyrics": inp.lyrics_text,
-                "youtube_url": inp.youtube_url, "genre": inp.genre, "year": inp.year,
-                "language": inp.language, "bpm": inp.bpm_override,
-                "video_filename": inp.video_path.name if inp.video_path else None,
-                "cover_filename": inp.cover_path.name if inp.cover_path else None}
-
-    return app
-
-
-def serve(cfg: Config) -> int:
-    import uvicorn
-    uvicorn.run(create_app(cfg), host=cfg.bind_host, port=cfg.port)
-    return 0

src/karaoke_maker/whisper_client.py

@@ -1,39 +0,0 @@
-from dataclasses import dataclass
-from pathlib import Path
-
-import httpx
-
-from .config import Config
-from .languages import LANGUAGES
-
-
-@dataclass
-class TranscriptSegment:
-    start: float
-    end: float
-    text: str
-
-
-def transcribe(cfg: Config, audio_path: Path, language: str | None = None,
-               client: httpx.Client | None = None) -> list[TranscriptSegment]:
-    headers = {}
-    if cfg.whisper_api_key:
-        headers["Authorization"] = f"Bearer {cfg.whisper_api_key}"
-    data = {"model": cfg.whisper_model, "response_format": "verbose_json"}
-    if language:
-        entry = LANGUAGES.get(language.lower())
-        data["language"] = entry.iso if entry else language
-    own = client is None
-    client = client or httpx.Client(timeout=600)
-    try:
-        with audio_path.open("rb") as f:
-            resp = client.post(
-                f"{cfg.whisper_url.rstrip('/')}/audio/transcriptions",
-                headers=headers, data=data,
-                files={"file": (audio_path.name, f, "audio/wav")})
-        resp.raise_for_status()
-        return [TranscriptSegment(s["start"], s["end"], s["text"].strip())
-                for s in resp.json().get("segments", [])]
-    finally:
-        if own:
-            client.close()

src/songtrace/audio_io.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+
+import soundfile as sf
+import torch
+
+
+def load_wav(path: Path) -> tuple[torch.Tensor, int]:
+    """Load a WAV file as a (channels, samples) float32 tensor.
+
+    Reads via soundfile rather than torchaudio.load, whose default backend
+    now requires the separate torchcodec package.
+    """
+    data, sr = sf.read(str(path), dtype="float32", always_2d=True)
+    return torch.from_numpy(data.T).contiguous(), sr

src/songtrace/cli.py

@@ -16,7 +16,7 @@ def _positive_float(value: str) -> float:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="karaoke-maker")
+    parser = argparse.ArgumentParser(prog="songtrace")
     parser.add_argument("--version", action="store_true")
     sub = parser.add_subparsers(dest="command")
 
@@ -72,7 +72,7 @@ def _cmd_make(args) -> int:
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
     if args.version:
-        print(f"karaoke-maker {version('karaoke-maker')}")
+        print(f"songtrace {version('songtrace')}")
         return 0
     if args.command == "make":
         return _cmd_make(args)

src/songtrace/config.py

@@ -0,0 +1,46 @@
+import os
+import tomllib
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+
+
+@dataclass
+class Config:
+    whisper_url: str
+    whisper_api_key: str | None = None
+    whisper_model: str = "whisper-1"
+    whisper_api: str = "openai"
+    output_dir: Path = Path("output")
+    work_dir: Path = Path("work")
+    creator: str = "songtrace"
+    demucs_model: str = "htdemucs_ft"
+    crepe_model: str = "full"
+    device: str = "cuda"
+    bind_host: str = "127.0.0.1"
+    port: int = 8000
+    # YouTube player clients to try, in order, until one yields a download.
+    # "default" means yt-dlp's own choice; see its extractor-args docs.
+    ytdlp_clients: list[str] = field(default_factory=lambda: ["default", "tv"])
+    ytdlp_cookies: Path | None = None
+    ytdlp_impersonate: str | None = None
+    ytdlp_pot_provider_url: str | None = None
+    # "auto" keeps yt-dlp current from PyPI, "bundled" uses only the copy
+    # installed with songtrace, and a release such as "2026.08.19" pins that.
+    ytdlp_version: str = "auto"
+
+
+_PATH_FIELDS = {"output_dir", "work_dir", "ytdlp_cookies"}
+
+
+def load_config(path: Path | None = None) -> Config:
+    if path is None:
+        env = os.environ.get("SONGTRACE_CONFIG")
+        path = Path(env) if env else Path.home() / ".config/songtrace/config.toml"
+    data = tomllib.loads(Path(path).read_text())
+    known = {f.name for f in fields(Config)}
+    unknown = set(data) - known
+    if unknown:
+        raise ValueError(f"unknown config keys: {', '.join(sorted(unknown))}")
+    for key in _PATH_FIELDS & set(data):
+        data[key] = Path(data[key])
+    return Config(**data)

src/songtrace/edits.py

@@ -0,0 +1,233 @@
+"""Manual edits to a song, kept apart from what the pipeline generates.
+
+Edits live in work/<slug>/edits.json, which no stage produces, so no rebuild
+removes them; grid lays them over the freshly generated notes every time. An
+edit is a whole lyric line as the user left it, timed in seconds so that a
+rebuild with a different BPM re-snaps it rather than breaking it.
+"""
+import difflib
+import json
+import math
+import time
+from pathlib import Path
+
+from .notes import MIN_NOTE_SEC, TimedNote, low_confidence_warnings
+
+EDITS_FILE = "edits.json"
+FINAL_FILE = "notes_final.json"
+KINDS = {":", "*", "F", "R", "G"}
+
+
+def _empty(lyrics: list[list[str]]) -> dict:
+    # grid: the BPM and GAP set in the editor, or None for the pipeline's own;
+    # breaks: line breaks moved by hand, keyed by the line each comes before
+    return {"lyrics": lyrics, "lines": {}, "stale": [], "grid": None, "breaks": {}}
+
+
+def load(work: Path, lyrics: list[list[str]]) -> dict:
+    """The song's edits, keyed to `lyrics`.
+
+    Edits are stored with the lyrics they were made against. When those
+    differ, each edited line is matched to its line in the new lyrics by
+    text and order; an edit whose line's words changed is set aside as stale
+    rather than applied to words it was not made for.
+    """
+    path = work / EDITS_FILE
+    if not path.exists():
+        return _empty(lyrics)
+    data = json.loads(path.read_text())
+    if data["lyrics"] != lyrics:
+        data = _remap(data, lyrics)
+        save(work, data)
+    return data
+
+
+def save(work: Path, data: dict) -> None:
+    path = work / EDITS_FILE
+    if not (data["lines"] or data["stale"] or data.get("grid") or data.get("breaks")):
+        path.unlink(missing_ok=True)
+        return
+    tmp = path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(data))
+    tmp.replace(path)
+
+
+def _remap(data: dict, lyrics: list[list[str]]) -> dict:
+    old = [tuple(line) for line in data["lyrics"]]
+    new = [tuple(line) for line in lyrics]
+    moved = {}
+    for tag, i1, i2, j1, _ in difflib.SequenceMatcher(
+            a=old, b=new, autojunk=False).get_opcodes():
+        if tag == "equal":
+            moved.update({i1 + k: j1 + k for k in range(i2 - i1)})
+    lines, stale = {}, list(data["stale"])
+    for key, edit in data["lines"].items():
+        to = moved.get(int(key))
+        if to is None:
+            stale.append(edit)
+        else:
+            lines[str(to)] = {**edit, "line_index": to}
+    # a moved break goes with the line it comes before; with that line gone,
+    # there is nothing left for it to separate
+    breaks = {str(moved[int(k)]): t for k, t in data.get("breaks", {}).items()
+              if int(k) in moved}
+    return {"lyrics": lyrics, "lines": lines, "stale": stale, "grid": data.get("grid"),
+            "breaks": breaks}
+
+
+def validate_notes(notes: list[dict]) -> list[dict]:
+    """The notes of a line edit, checked and reduced to what is stored."""
+    clean = []
+    for n in notes:
+        try:
+            note = {"start": float(n["start"]), "duration": float(n["duration"]),
+                    "pitch": int(n["pitch"]), "text": str(n["text"]),
+                    "kind": str(n.get("kind", ":"))}
+        except (KeyError, TypeError, ValueError):
+            raise ValueError(f"malformed note {n!r}")
+        if note["start"] < 0 or note["duration"] <= 0:
+            raise ValueError(f"a note needs start >= 0 and duration > 0: {n!r}")
+        if note["kind"] not in KINDS:
+            raise ValueError(f"unknown note kind {note['kind']!r}")
+        if not note["text"].strip():
+            raise ValueError("a note needs text")
+        clean.append(note)
+    return sorted(clean, key=lambda n: n["start"])
+
+
+def set_line(data: dict, index: int, notes: list[dict]) -> None:
+    data["lines"][str(index)] = {
+        "line_index": index, "words": data["lyrics"][index],
+        "notes": validate_notes(notes), "saved_at": time.time()}
+
+
+def clear_line(data: dict, index: int) -> bool:
+    return data["lines"].pop(str(index), None) is not None
+
+
+def set_breaks(data: dict, changes: dict) -> None:
+    """Move line breaks, each keyed by the line it comes before, to a time in
+    seconds; None puts one back to where the notes alone would place it."""
+    breaks = dict(data.get("breaks", {}))
+    for key, t in changes.items():
+        try:
+            line = int(key)
+        except (TypeError, ValueError):
+            raise ValueError(f"a break is keyed by the line it comes before, not {key!r}")
+        if not 0 < line < len(data["lyrics"]):
+            raise ValueError(f"no line {line} for a break to come before")
+        if t is None:
+            breaks.pop(str(line), None)
+            continue
+        try:
+            t = float(t)
+        except (TypeError, ValueError):
+            raise ValueError(f"a break needs a time in seconds, not {t!r}")
+        if not (math.isfinite(t) and t >= 0):
+            raise ValueError(f"a break needs a time of 0 or more, not {t}")
+        breaks[str(line)] = t
+    data["breaks"] = breaks
+
+
+def set_grid(data: dict, bpm, gap_ms) -> None:
+    """Set the chart's BPM (UltraStar's, a quarter of a beat per beat) and GAP."""
+    try:
+        bpm, gap_ms = float(bpm), float(gap_ms)
+    except (TypeError, ValueError):
+        raise ValueError("bpm and gap_ms must be numbers")
+    if not (math.isfinite(bpm) and 0 < bpm <= 2000):
+        raise ValueError(f"bpm must be above 0 and at most 2000, not {bpm}")
+    if not (math.isfinite(gap_ms) and gap_ms >= 0):
+        raise ValueError(f"gap_ms must be 0 or more, not {gap_ms}")
+    data["grid"] = {"bpm": bpm, "gap_ms": gap_ms}
+
+
+def clear_grid(data: dict) -> bool:
+    had = bool(data.get("grid"))
+    data["grid"] = None
+    return had
+
+
+def merge(notes: list[dict], breaks: list[float], data: dict
+          ) -> tuple[list[dict], list[float]]:
+    """Generated notes and breaks with every edited line laid over them.
+
+    An edited line replaces the generated notes of that line, and the user's
+    timing wins: generated notes of earlier lines are cut back to end where it
+    starts, and those of later lines to start where it ends. Line breaks next
+    to an edited line move to the middle of the gap it leaves; a break moved
+    by hand stays where it was put, kept between the lines it separates.
+    """
+    edited = {int(k): e["notes"] for k, e in data["lines"].items()}
+    moved = {int(k): t for k, t in data.get("breaks", {}).items()}
+    if not edited and not moved:
+        return notes, breaks
+    spans = {li: (ns[0]["start"], ns[-1]["start"] + ns[-1]["duration"])
+             for li, ns in edited.items() if ns}
+    kept = []
+    for n in notes:
+        li = n["line_index"]
+        if li in edited:
+            continue
+        start, end = n["start"], n["start"] + n["duration"]
+        for eli, (a, b) in spans.items():
+            if li < eli:
+                end = min(end, a)
+            elif li > eli:
+                start = max(start, b)
+        if (start, end) == (n["start"], n["start"] + n["duration"]):
+            kept.append(n)
+        elif end - start >= MIN_NOTE_SEC:
+            kept.append({**n, "start": start, "duration": end - start})
+    for li, ns in edited.items():
+        kept += [{**n, "line_index": li, "low_confidence": False} for n in ns]
+    kept.sort(key=lambda n: (n["start"], n["line_index"]))
+
+    def line_after(t: float) -> int | None:
+        return next((n["line_index"] for n in notes if n["start"] >= t), None)
+
+    first = {}
+    last = {}
+    for n in kept:
+        first.setdefault(n["line_index"], n)
+        last[n["line_index"]] = n
+    order = sorted(first, key=lambda li: first[li]["start"])
+    out_breaks = []
+    for prev, nxt in zip(order, order[1:]):
+        end = last[prev]["start"] + last[prev]["duration"]
+        if nxt in moved:
+            # where it was put, but never inside either line's notes
+            out_breaks.append(min(max(moved[nxt], end), max(first[nxt]["start"], end)))
+            continue
+        if prev not in edited and nxt not in edited:
+            # the generated break between these two lines, untouched
+            gen = [t for t in breaks if line_after(t) == nxt]
+            if gen:
+                out_breaks.append(gen[0])
+                continue
+        out_breaks.append((end + first[nxt]["start"]) / 2)
+    return kept, out_breaks
+
+
+def finalize(work: Path, lyrics: list[list[str]]) -> dict:
+    """The song as it is to be charted: generated notes with the edits laid
+    over them, warnings brought up to date, written to notes_final.json."""
+    generated = json.loads((work / "notes_sec.json").read_text())
+    data = load(work, lyrics)
+    notes, breaks = merge(generated["notes"], generated["breaks"], data)
+    warnings = generated.get("warnings", [])
+    if data["lines"]:
+        # low-confidence warnings must describe the merged notes, so a line
+        # the user fixed stops being reported; the others are about lyrics
+        warnings = (low_confidence_warnings([TimedNote(**n) for n in notes])
+                    + [w for w in warnings if "low-confidence" not in w])
+    if data["stale"]:
+        n = len(data["stale"])
+        warnings.append(f"{n} edited line{' no longer matches' if n == 1 else 's no longer match'}"
+                        " the lyrics; set aside in the editor")
+    final = {"notes": notes, "breaks": breaks, "warnings": warnings,
+             "edited_lines": sorted(int(k) for k in data["lines"]),
+             "stale": data["stale"], "grid": data.get("grid"),
+             "moved_breaks": sorted(int(k) for k in data.get("breaks", {}))}
+    (work / FINAL_FILE).write_text(json.dumps(final))
+    return final

src/songtrace/grid.py

@@ -3,7 +3,11 @@ from pathlib import Path
 
 import numpy as np
 
-from .ultrastar import LineBreak, Note, UltraStarSong, format_bpm
+from .ultrastar import (LineBreak, Note, UltraStarSong, format_bpm, get_header,
+                        parse_bpm, parse_ultrastar, serialize_ultrastar)
+
+
+TEMPO_FILE = "tempo.json"
 
 
 def detect_bpm(instrumental_path: Path) -> float:
@@ -25,11 +29,20 @@ def scale_bpm(bpm: float) -> float:
 
 
 def to_ultrastar(notes: list[dict], breaks: list[float], file_bpm: float,
-                 headers: list[tuple[str, str]]) -> UltraStarSong:
+                 headers: list[tuple[str, str]],
+                 gap_ms: float | None = None) -> UltraStarSong:
+    """Snap notes to the beat grid. GAP defaults to the first note's start; a
+    GAP set later than that would put notes on negative beats, which players
+    reject, so it moves back by whole beats, keeping the grid where it was."""
     if not notes:
         raise ValueError("no notes to place on the beat grid")
-    gap_ms = round(notes[0]["start"] * 1000)
     spb = 60 / (4 * file_bpm)
+    first_ms = notes[0]["start"] * 1000
+    if gap_ms is None:
+        gap_ms = first_ms
+    elif gap_ms > first_ms:
+        gap_ms -= math.ceil((gap_ms - first_ms) / (spb * 1000)) * spb * 1000
+    gap_ms = max(0, round(gap_ms))
 
     def beat(t: float) -> int:
         return round((t - gap_ms / 1000) / spb)
@@ -49,10 +62,27 @@ def to_ultrastar(notes: list[dict], breaks: list[float], file_bpm: float,
         else:
             b = max(beat(t), cursor)
             length = max(1, beat(t + n["duration"]) - beat(t))
-            body.append(Note(kind=":", beat=b, length=length, pitch=n["pitch"],
-                             text=n["text"]))
+            body.append(Note(kind=n.get("kind", ":"), beat=b, length=length,
+                             pitch=n["pitch"], text=n["text"]))
             cursor = b + length
     out_headers = list(headers)
     out_headers.append(("BPM", format_bpm(file_bpm)))
     out_headers.append(("GAP", str(gap_ms)))
     return UltraStarSong(headers=out_headers, body=body)
+
+
+def rechart(txt_path: Path, notes: list[dict], breaks: list[float],
+            bpm: float | None = None, gap_ms: float | None = None) -> None:
+    """Replace a chart's notes, keeping its headers and, unless given new
+    ones, its BPM.
+
+    For an edit saved from the editor: the packaged chart's headers may differ
+    from the work copy's (a re-encoded #VIDEO, a dropped #COVER), so each
+    keeps its own.
+    """
+    song = parse_ultrastar(txt_path.read_text(encoding="utf-8"))
+    if bpm is None:
+        bpm = parse_bpm(get_header(song, "BPM"))
+    headers = [(k, v) for k, v in song.headers if k.upper() not in ("BPM", "GAP")]
+    txt_path.write_text(serialize_ultrastar(to_ultrastar(notes, breaks, bpm, headers, gap_ms)),
+                        encoding="utf-8")

src/songtrace/models.py

@@ -0,0 +1,47 @@
+"""Handing the GPU back between stages.
+
+The GPU this runs on is shared, and `songtrace serve` outlives every job it
+runs, so a stage that caches its weights holds VRAM until the process exits —
+including while a later stage is waiting on the Whisper server, which can be
+minutes of a GPU nothing is using. Two things have to be undone: the caches
+themselves, and PyTorch's allocator, which keeps freed blocks for reuse rather
+than returning them to the driver.
+
+A stage that caches a model registers how to drop it with @on_release, so this
+module needs to know nothing about the pipeline. Registration happens at import
+time, which run_pipeline has already done by the time it calls release().
+"""
+import gc
+import sys
+from typing import Callable
+
+_callbacks: list[Callable[[], None]] = []
+
+
+def on_release(fn: Callable[[], None]) -> Callable[[], None]:
+    """Register a callback that drops a cached model."""
+    _callbacks.append(fn)
+    return fn
+
+
+def release() -> int:
+    """Drop every cached model and return its VRAM to the driver.
+
+    Answers the bytes handed back, which is the only part of this a caller can
+    show someone. Safe whenever: a stage that never loaded anything has nothing
+    to drop, and the allocator is left alone unless this process actually
+    initialised CUDA.
+    """
+    for callback in _callbacks:
+        callback()
+    # weights reach the allocator's free list only once the last reference
+    # goes, and a module graph is cyclic enough to outlive refcounting
+    gc.collect()
+    torch = sys.modules.get("torch")
+    if torch is None or not torch.cuda.is_available():
+        return 0
+    if not torch.cuda.is_initialized():
+        return 0
+    before = torch.cuda.memory_reserved()
+    torch.cuda.empty_cache()
+    return max(before - torch.cuda.memory_reserved(), 0)

src/songtrace/notes.py

@@ -7,7 +7,17 @@ import pyphen
 from .languages import LANGUAGES
 
 CONF_MASK = 0.5          # pitch frames below this are unvoiced
-LOW_SCORE = 0.5          # word alignment score below this -> low_confidence
+# A word is low-confidence when it scores below this share of the song's
+# median alignment score: the scale differs a lot from song to song, so no
+# fixed cutoff holds across them.
+LOW_SCORE_OF_MEDIAN = 0.25
+# ...or when no one sings a word that fast, or it was stretched over more than
+# it can be holding.
+MIN_WORD_SEC = 0.08
+MAX_WORD_SEC = 3.0
+# Flagged notes closer than this share one warning, so the list reads as
+# places to look rather than one line per note.
+WARN_GAP_SEC = 2.0
 SPLIT_SEMITONES = 0.8
 MIN_SEG_SEC = 0.05
 MIN_NOTE_SEC = 0.05      # alignment may hand us zero-length words
@@ -23,6 +33,8 @@ class TimedNote:
     pitch: int            # UltraStar semitone (0 = C4 = MIDI 60)
     text: str             # display text incl. leading space / "~"
     low_confidence: bool
+    line_index: int
+    kind: str = ":"       # UltraStar note type; generated notes are all normal
 
 
 def hz_to_midi_float(hz: float) -> float:
@@ -78,10 +90,12 @@ def syllabify(word: str, language: str | None) -> list[str]:
     return parts or [word]
 
 
-def build_notes(rows: list[dict], times, f0, conf, language: str | None
+def build_notes(rows: list[dict], times, f0, conf, language: str | None,
+                dropped_lines=(), missing_spans=(), ref_lines=None
                 ) -> tuple[list[TimedNote], list[float], list[str]]:
     notes: list[TimedNote] = []
     breaks: list[float] = []
+    floor = LOW_SCORE_OF_MEDIAN * float(np.median([r["score"] for r in rows])) if rows else 0.0
     prev_line, prev_end = None, 0.0
     for row in rows:
         if prev_line is not None and row["line_index"] > prev_line:
@@ -92,22 +106,26 @@ def build_notes(rows: list[dict], times, f0, conf, language: str | None
         if not segs:
             pitch = notes[-1].pitch if notes else 0
             notes.append(_note(row["start"], row["end"] - row["start"], pitch,
-                               _text(row["word"], 0, line_initial), True))
+                               _text(row["word"], 0, line_initial), True,
+                               row["line_index"]))
             continue
-        low = row["score"] < LOW_SCORE
+        low = (row["score"] < floor
+               or not MIN_WORD_SEC <= row["end"] - row["start"] <= MAX_WORD_SEC)
         sylls = syllabify(row["word"], language)
         if len(segs) < len(sylls):
             segs = _subdivide(segs, len(sylls))
         for i, (s, e, midi) in enumerate(segs):
             text = _text(sylls[i], i, line_initial) if i < len(sylls) else "~"
-            notes.append(_note(s, e - s, round(midi) - 60, text, low))
+            notes.append(_note(s, e - s, round(midi) - 60, text, low,
+                               row["line_index"]))
     _deoverlap(notes)
-    return notes, breaks, _warnings(notes)
+    return notes, breaks, _warnings(notes, dropped_lines, missing_spans, ref_lines or [])
 
 
 def _note(start: float, duration: float, pitch: int, text: str,
-          low: bool) -> TimedNote:
-    return TimedNote(float(start), float(duration), int(pitch), text, low)
+          low: bool, line_index: int) -> TimedNote:
+    return TimedNote(float(start), float(duration), int(pitch), text, low,
+                     int(line_index))
 
 
 def _deoverlap(notes: list[TimedNote]) -> None:
@@ -153,15 +171,40 @@ def _fmt(t: float) -> str:
     return f"{int(t // 60)}:{int(t % 60):02d}"
 
 
-def _warnings(notes: list[TimedNote]) -> list[str]:
-    warnings, run = [], []
-    for n in list(notes) + [None]:
-        if n is not None and n.low_confidence:
-            run.append(n)
-        elif run:
-            first, last = run[0], run[-1]
-            warnings.append(
-                f"{len(run)} low-confidence note{'' if len(run) == 1 else 's'} "
-                f"near {_fmt(first.start)}–{_fmt(last.start + last.duration)}")
-            run = []
+def low_confidence_warnings(notes: list[TimedNote]) -> list[str]:
+    runs: list[list[TimedNote]] = []
+    for n in notes:
+        if not n.low_confidence:
+            continue
+        last = runs[-1][-1] if runs else None
+        if last is not None and n.start - (last.start + last.duration) < WARN_GAP_SEC:
+            runs[-1].append(n)
+        else:
+            runs.append([n])
+    return [
+        f"{len(run)} low-confidence note{'' if len(run) == 1 else 's'} "
+        f"near {_fmt(run[0].start)}–{_fmt(run[-1].start + run[-1].duration)}"
+        for run in runs]
+
+
+def _warnings(notes: list[TimedNote], dropped_lines=(), missing_spans=(),
+             ref_lines=()) -> list[str]:
+    warnings = low_confidence_warnings(notes)
+    for group in _consecutive_runs(dropped_lines):
+        n = len(group)
+        text = " ".join(ref_lines[group[0]]) if group[0] < len(ref_lines) else ""
+        warnings.append(
+            f"{n} line{'' if n == 1 else 's'} dropped (not sung) near \"{text}\"")
+    for a, b in missing_spans:
+        warnings.append(f"missing lyrics near {_fmt(a)}–{_fmt(b)}")
     return warnings
+
+
+def _consecutive_runs(indices) -> list[list[int]]:
+    runs = []
+    for i in sorted(indices):
+        if runs and i == runs[-1][-1] + 1:
+            runs[-1].append(i)
+        else:
+            runs.append([i])
+    return runs

src/songtrace/pipeline.py

@@ -3,6 +3,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Callable
 
+from . import models
 from .config import Config
 
 class PipelineError(Exception):
@@ -45,6 +46,16 @@ def song_slug(inp: SongInput) -> str:
     name = f"{inp.artist} - {inp.title}"
     return name.replace("/", "").replace("\0", "")
 
+def read_warnings(work: Path) -> list[str]:
+    # grid's copy accounts for the user's edits; notes' is all a song built
+    # before edits existed has
+    notes_file = work / "notes_final.json"
+    if not notes_file.exists():
+        notes_file = work / "notes_sec.json"
+    if not notes_file.exists():
+        return []
+    return json.loads(notes_file.read_text()).get("warnings", [])
+
 def _real_stages() -> list[Stage]:
     from . import stages
     return stages.all_stages()
@@ -68,9 +79,14 @@ def run_pipeline(inp: SongInput, cfg: Config, log=print,
             log(f"[{stage.name}] cached, skipping")
             continue
         log(f"[{stage.name}] running")
-        stage.run(ctx)
-    warnings = []
-    notes_file = work / "notes_sec.json"
-    if notes_file.exists():
-        warnings = json.loads(notes_file.read_text()).get("warnings", [])
-    return PipelineResult(output_dir=cfg.output_dir / song_slug(inp), warnings=warnings)
+        # per stage rather than per job: each model is used by one stage, so
+        # holding it past that only keeps VRAM from whatever else wants it
+        try:
+            stage.run(ctx)
+        finally:
+            # logged only when it actually gave something back, so the line is
+            # evidence rather than noise on a box where this matters
+            if freed := models.release():
+                log(f"[{stage.name}] released {freed / 2**20:.0f} MiB of GPU memory")
+    return PipelineResult(output_dir=cfg.output_dir / song_slug(inp),
+                          warnings=read_warnings(work))

src/songtrace/rebuild.py

@@ -38,6 +38,17 @@ def plan(old: SongInput, new: SongInput) -> str | None:
     return min((FIELD_STAGE[f] for f in changed), key=STAGE_ORDER.index)
 
 
+def earliest(*stages: str | None) -> str | None:
+    """The earliest of the stages given, ignoring None ("nothing forced").
+
+    An operator's explicit choice is combined with plan()'s rather than
+    replacing it: the planner's stage is the latest that is still correct for
+    the edit, so a choice may only ever redo more.
+    """
+    named = [s for s in stages if s]
+    return min(named, key=STAGE_ORDER.index) if named else None
+
+
 def relocate_work(old: SongInput, new: SongInput, cfg: Config) -> bool:
     """Move the cached work dir when title/artist changed its slug.
 

src/songtrace/stages/acquire.py

@@ -0,0 +1,93 @@
+import json
+import shutil
+from pathlib import Path
+
+from .. import ytdlp
+from ..config import Config
+from ..media import ffmpeg
+from ..pipeline import Ctx, PipelineError, Stage
+
+IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp", ".avif", ".gif"}
+# yt-dlp's in-progress scratch files, which a failed attempt leaves behind.
+PARTIAL_EXTENSIONS = {".part", ".ytdl", ".temp"}
+
+
+def _classify_downloads(dest: Path) -> tuple[Path, Path | None]:
+    files = [p for p in dest.glob("source_video.*")
+             if p.suffix.lower() not in PARTIAL_EXTENSIONS]
+    thumbs = [p for p in files if p.suffix.lower() in IMAGE_EXTENSIONS]
+    videos = [p for p in files if p.suffix.lower() not in IMAGE_EXTENSIONS]
+    if not videos:
+        raise PipelineError("yt-dlp produced no video file")
+    video = max(videos, key=lambda p: p.stat().st_size)
+    return video, thumbs[0] if thumbs else None
+
+
+def _ydl_args(cfg: Config, dest: Path, client: str, url: str) -> list[str]:
+    args = [
+        "--output", str(dest / "source_video.%(ext)s"),
+        "--format", "bestvideo*+bestaudio/best",
+        "--write-thumbnail", "--no-playlist", "--no-progress",
+        "--retries", "10", "--fragment-retries", "10",
+        "--extractor-retries", "5",
+    ]
+    if client != "default":
+        args += ["--extractor-args", f"youtube:player_client={client}"]
+    if cfg.ytdlp_pot_provider_url:
+        args += ["--extractor-args",
+                 f"youtubepot-bgutilhttp:base_url={cfg.ytdlp_pot_provider_url}"]
+    if cfg.ytdlp_cookies:
+        args += ["--cookies", str(cfg.ytdlp_cookies)]
+    if cfg.ytdlp_impersonate:
+        args += ["--impersonate", cfg.ytdlp_impersonate]
+    return [*args, "--", url]
+
+
+def download_youtube(url: str, dest: Path, cfg: Config,
+                     log=print) -> tuple[Path, Path | None]:
+    clients = list(cfg.ytdlp_clients) or ["default"]
+    tried: list[str] = []
+    last: Exception | None = None
+    # If every copy fails, look for a release newer than the daily check found.
+    for refresh in (False, True):
+        for ydl in ytdlp.candidates(cfg, log, refresh):
+            if ydl.version in tried:
+                continue
+            tried.append(ydl.version)
+            for client in clients:
+                try:
+                    ydl.run(_ydl_args(cfg, dest, client, url), log)
+                    return _classify_downloads(dest)
+                except PipelineError as e:
+                    last = e
+                    log(f"yt-dlp {ydl.version} player_client={client} "
+                        f"failed: {e}")
+    raise PipelineError(
+        f"yt-dlp {', '.join(tried)} could not download {url} after trying "
+        f"player_client={', '.join(clients)}. Last error: {last}. "
+        "See the yt-dlp options in config.toml (cookies, impersonation, "
+        "PO token provider).")
+
+
+def _run(ctx: Ctx) -> None:
+    if bool(ctx.inp.youtube_url) == bool(ctx.inp.video_path):
+        raise PipelineError("provide exactly one of youtube_url / video_path")
+    thumb = None
+    if ctx.inp.youtube_url:
+        video, thumb = download_youtube(ctx.inp.youtube_url, ctx.work,
+                                       ctx.cfg, ctx.log)
+    else:
+        video = ctx.work / f"source_video{ctx.inp.video_path.suffix}"
+        shutil.copyfile(ctx.inp.video_path, video)
+    ffmpeg("-i", str(video), "-vn", "-ac", "2", "-ar", "44100",
+           str(ctx.work / "audio.wav"))
+    meta = {"video_file": video.name, "thumbnail": thumb.name if thumb else None}
+    (ctx.work / "meta.json").write_text(json.dumps(meta))
+
+
+def acquire_stage() -> Stage:
+    return Stage(
+        name="acquire",
+        outputs=lambda ctx: [ctx.work / "meta.json", ctx.work / "audio.wav"],
+        run=_run,
+    )

src/songtrace/stages/align.py

@@ -0,0 +1,200 @@
+import json
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+
+from ..lyrics import alignment_token, normalize_lyrics
+from ..models import on_release
+from ..pipeline import Ctx, PipelineError, Stage
+from ..whisper_client import TranscriptSegment
+from .transcribe import (classify_lyrics_match, load_transcript, lyrics_similarity,
+                         recovered_spans, vocal_sections)
+
+SIMILARITY_THRESHOLD = 0.4
+# MMS_FA's wildcard token: any audio the transcript does not cover
+STAR = "*"
+# Singing is audio within this much of the stem's loud level; separation
+# bleed sits far below it.
+SINGING_BELOW_LOUD_DB = 25.0
+# Shorter stretches are breaths, ad-libs or Whisper's loose segment edges.
+MIN_UNHEARD_SEC = 3.0
+
+# a stage aligns section by section, so the model is cached across the calls
+# within one run and dropped at the end of it
+_model_cache = {}
+
+
+def _get_model(device: str):
+    if device not in _model_cache:
+        from torchaudio.pipelines import MMS_FA as bundle
+        _model_cache[device] = bundle.get_model().to(device)
+    return _model_cache[device]
+
+
+@on_release
+def unload_model() -> None:
+    _model_cache.clear()
+
+
+def force_align_section(vocals_path: Path, start: float, end: float,
+                        tokens: list[str], device: str) -> list[tuple[float, float, float]]:
+    import torch
+    import torchaudio
+    from torchaudio.pipelines import MMS_FA as bundle
+
+    from ..audio_io import load_wav
+
+    waveform, sr = load_wav(vocals_path)
+    waveform = waveform.mean(0, keepdim=True)
+    lo, hi = int(start * sr), min(int(end * sr), waveform.shape[1])
+    waveform = torchaudio.functional.resample(
+        waveform[:, lo:hi], sr, bundle.sample_rate)
+    # MMS_FA only models a-z and apostrophe; anything else becomes the star token.
+    vocab = bundle.get_dict()
+    tokens = ["".join(c if c in vocab else STAR for c in t) for t in tokens]
+    with torch.inference_mode():
+        emission, _ = _get_model(device)(waveform.to(device))
+        spans = bundle.get_aligner()(emission[0], bundle.get_tokenizer()(tokens))
+    frame = (hi - lo) / sr / emission.shape[1]
+    return [(start + s[0].start * frame,
+             start + s[-1].end * frame,
+             sum(t.score for t in s) / len(s)) for s in spans]
+
+
+def untranscribed_singing(vocals_path: Path, segments,
+                          frame: float = 0.05) -> list[tuple[float, float]]:
+    """Stretches of the vocal stem with singing in them but no transcript."""
+    data, sr = sf.read(str(vocals_path), dtype="float32", always_2d=True)
+    hop = int(sr * frame)
+    n = len(data) // hop
+    if n == 0:
+        return []
+    rms = np.sqrt((data[:n * hop].mean(1).reshape(n, hop) ** 2).mean(1))
+    db = 20 * np.log10(rms + 1e-10)
+    sung = db >= np.quantile(db, 0.9) - SINGING_BELOW_LOUD_DB
+    times = np.arange(n) * frame
+    for s in segments:
+        sung[(times >= min(s.start, s.end)) & (times < max(s.start, s.end))] = False
+    spans, start = [], None
+    for t, on in zip(times, sung):
+        if on and start is None:
+            start = float(t)
+        elif not on and start is not None:
+            spans.append((start, float(t)))
+            start = None
+    if start is not None:
+        spans.append((start, float(times[-1] + frame)))
+    # a breath or a quiet syllable must not split one unsung passage in two
+    merged: list[list[float]] = []
+    for a, b in spans:
+        if merged and a - merged[-1][1] < 1.0:
+            merged[-1][1] = b
+        else:
+            merged.append([a, b])
+    return [(a, b) for a, b in merged if b - a >= MIN_UNHEARD_SEC]
+
+
+def _assign_lines_to_sections(line_indices: list[int], sections) -> list[list[int]]:
+    """Split matched lyric line indices across vocal sections proportionally to section duration."""
+    total = sum(b - a for a, b in sections) or 1.0
+    n = len(line_indices)
+    groups, elapsed, start = [], 0.0, 0
+    for i, (a, b) in enumerate(sections):
+        elapsed += b - a
+        stop = n if i == len(sections) - 1 else min(n, round(n * elapsed / total))
+        groups.append(line_indices[start:max(stop, start)])
+        start = max(stop, start)
+    return groups
+
+
+def _interpolate(rows: list[dict], lo_bound: float, hi_bound: float) -> None:
+    """Give rows left without times evenly spaced spans between their aligned neighbours."""
+    i = 0
+    while i < len(rows):
+        if rows[i]["start"] is not None:
+            i += 1
+            continue
+        j = i
+        while j < len(rows) and rows[j]["start"] is None:
+            j += 1
+        lo = rows[i - 1]["end"] if i else lo_bound
+        hi = max(rows[j]["start"] if j < len(rows) else hi_bound, lo)
+        step = (hi - lo) / (j - i)
+        for k in range(i, j):
+            rows[k]["start"] = lo + (k - i) * step
+            rows[k]["end"] = rows[k]["start"] + step
+        i = j
+
+
+def _enforce_monotonic(rows: list[dict]) -> None:
+    prev = 0.0
+    for r in rows:
+        r["start"] = max(r["start"], prev)
+        r["end"] = prev = max(r["end"], r["start"])
+
+
+def _align_section(vocals: Path, sec: tuple[float, float], words: list[tuple[str, int]],
+                   language: str | None, device: str) -> list[dict]:
+    tokens = [alignment_token(w, language) for w, _ in words]
+    # A star before, between and after lines lets speech, laughter or an
+    # ad-lib there go unexplained rather than claim the next line's letters.
+    seq, prev_line = [], None
+    for (_, line_index), token in zip(words, tokens):
+        if not token:
+            continue
+        if line_index != prev_line:
+            seq.append(STAR)
+            prev_line = line_index
+        seq.append(token)
+    if seq:
+        seq.append(STAR)
+    spans = force_align_section(vocals, sec[0], sec[1], seq, device) if seq else []
+    aligned = iter(span for span, token in zip(spans, seq) if token != STAR)
+    rows, blank = [], (None, None, 0.0)
+    for (word, line_index), token in zip(words, tokens):
+        start, end, score = next(aligned, blank) if token else blank
+        rows.append({"word": word, "start": start, "end": end,
+                     "score": score, "line_index": line_index})
+    _interpolate(rows, sec[0], sec[1])
+    return rows
+
+
+def _run(ctx: Ctx) -> None:
+    ref = normalize_lyrics(ctx.inp.lyrics_text)
+    segments = sorted(load_transcript(ctx), key=lambda s: s.start)
+    sim = lyrics_similarity(segments, ref)
+    if sim < SIMILARITY_THRESHOLD:
+        raise PipelineError(
+            f"lyrics don't match audio (similarity {sim:.2f}) — "
+            "wrong lyrics or wrong recording?")
+    vocals = ctx.work / "vocals.wav"
+    unheard = untranscribed_singing(vocals, segments)
+    dropped_lines, missing_spans = classify_lyrics_match(segments, ref,
+                                                         unheard=unheard)
+    # lines Whisper missed are aligned against the singing it had no text for;
+    # only that singing, so an untranscribed ad-lib cannot draw lines into it
+    recovered = [TranscriptSegment(a, b, "")
+                 for a, b in recovered_spans(segments, ref, unheard)]
+    # normalised so an inverted span can never collapse a section onto one instant
+    sections = [(min(a, b), max(a, b))
+                for a, b in vocal_sections(segments + recovered)]
+    matched = [i for i in range(len(ref.lines)) if i not in set(dropped_lines)]
+    rows = []
+    for sec, line_idxs in zip(sections, _assign_lines_to_sections(matched, sections)):
+        words = [(w, li) for li in line_idxs for w in ref.lines[li]]
+        if words:
+            rows.extend(_align_section(vocals, sec, words, ctx.inp.language,
+                                       ctx.cfg.device))
+    _enforce_monotonic(rows)
+    (ctx.work / "alignment.json").write_text(json.dumps(rows))
+    (ctx.work / "align_meta.json").write_text(json.dumps({
+        "dropped_lines": dropped_lines,
+        "missing_spans": [list(s) for s in missing_spans],
+    }))
+
+
+def align_stage() -> Stage:
+    return Stage(name="align",
+                 outputs=lambda ctx: [ctx.work / "alignment.json"],
+                 run=_run)

src/songtrace/stages/grid.py

@@ -1,13 +1,16 @@
 import json
 from pathlib import Path
 
-from .. import grid
+from .. import edits, grid
+from ..lyrics import normalize_lyrics
 from ..pipeline import Ctx, PipelineError, Stage, song_slug
 from ..ultrastar import serialize_ultrastar
 
 
 def _run(ctx: Ctx) -> None:
-    data = json.loads((ctx.work / "notes_sec.json").read_text())
+    data = edits.finalize(ctx.work, normalize_lyrics(ctx.inp.lyrics_text).lines)
+    if data["edited_lines"]:
+        ctx.log(f"[grid] kept {len(data['edited_lines'])} edited line(s)")
     meta = json.loads((ctx.work / "meta.json").read_text())
     if ctx.inp.bpm_override is not None:
         bpm = ctx.inp.bpm_override
@@ -16,6 +19,12 @@ def _run(ctx: Ctx) -> None:
             bpm = grid.scale_bpm(grid.detect_bpm(ctx.work / "instrumental.wav"))
         except ValueError:
             raise PipelineError("could not detect a usable tempo - is the audio silent?")
+    # the pipeline's own tempo, which RESET in the editor returns to
+    (ctx.work / grid.TEMPO_FILE).write_text(json.dumps({"bpm": bpm}))
+    gap_ms = None
+    if data["grid"]:
+        bpm, gap_ms = data["grid"]["bpm"], data["grid"]["gap_ms"]
+        ctx.log("[grid] using the BPM and GAP set in the editor")
     slug = song_slug(ctx.inp)
     video_ext = Path(meta["video_file"]).suffix
     headers = [("TITLE", ctx.inp.title), ("ARTIST", ctx.inp.artist)]
@@ -28,7 +37,7 @@ def _run(ctx: Ctx) -> None:
     headers += [("CREATOR", ctx.cfg.creator), ("MP3", f"{slug}.mp3"),
                 ("COVER", f"{slug}.jpg"), ("VIDEO", f"{slug}{video_ext}")]
     try:
-        song = grid.to_ultrastar(data["notes"], data["breaks"], bpm, headers)
+        song = grid.to_ultrastar(data["notes"], data["breaks"], bpm, headers, gap_ms)
     except ValueError:
         raise PipelineError("no notes were generated - the lyrics may not match the audio")
     (ctx.work / "song.txt").write_text(serialize_ultrastar(song), encoding="utf-8")
@@ -36,5 +45,6 @@ def _run(ctx: Ctx) -> None:
 
 def grid_stage() -> Stage:
     return Stage(name="grid",
-                 outputs=lambda ctx: [ctx.work / "song.txt"],
+                 outputs=lambda ctx: [ctx.work / "song.txt",
+                                      ctx.work / edits.FINAL_FILE],
                  run=_run)

src/songtrace/stages/notes.py

@@ -3,6 +3,7 @@ from dataclasses import asdict
 
 import numpy as np
 
+from ..lyrics import normalize_lyrics
 from ..notes import build_notes
 from ..pipeline import Ctx, Stage
 
@@ -10,8 +11,15 @@ from ..pipeline import Ctx, Stage
 def _run(ctx: Ctx) -> None:
     rows = json.loads((ctx.work / "alignment.json").read_text())
     data = np.load(ctx.work / "pitch.npz")
+    meta_path = ctx.work / "align_meta.json"
+    meta = json.loads(meta_path.read_text()) if meta_path.exists() else {}
+    dropped_lines = meta.get("dropped_lines", [])
+    missing_spans = [tuple(s) for s in meta.get("missing_spans", [])]
+    ref_lines = normalize_lyrics(ctx.inp.lyrics_text).lines
     notes, breaks, warnings = build_notes(
-        rows, data["times"], data["f0"], data["conf"], ctx.inp.language)
+        rows, data["times"], data["f0"], data["conf"], ctx.inp.language,
+        dropped_lines=dropped_lines, missing_spans=missing_spans,
+        ref_lines=ref_lines)
     (ctx.work / "notes_sec.json").write_text(json.dumps({
         "notes": [asdict(n) for n in notes],
         "breaks": breaks,

src/songtrace/stages/package.py

@@ -51,11 +51,15 @@ def _run(ctx: Ctx) -> None:
     meta = json.loads((ctx.work / "meta.json").read_text())
     src_video = ctx.work / meta["video_file"]
     fmt, codec = ffprobe_codec(src_video)
+    # The video is background only: the song's audio is #MP3, and the two are
+    # the same recording. A player that does not mute the video plays both at
+    # once, which is heard as an echo, so the audio track is dropped here.
     if (fmt, codec) in GOOD_VIDEO:
-        shutil.copyfile(src_video, out / f"{slug}{src_video.suffix}")
+        ffmpeg("-i", str(src_video), "-c", "copy", "-an",
+               str(out / f"{slug}{src_video.suffix}"))
     else:
         ffmpeg("-i", str(src_video), "-c:v", "libx264", "-crf", "20",
-               "-preset", "medium", "-c:a", "aac", str(out / f"{slug}.mp4"))
+               "-preset", "medium", "-an", str(out / f"{slug}.mp4"))
         _set_header(txt, "VIDEO", f"{slug}.mp4")
     cover_src = ctx.inp.cover_path
     if cover_src is None and meta.get("thumbnail"):

src/songtrace/stages/pitch.py

@@ -0,0 +1,60 @@
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from ..models import on_release
+from ..pipeline import Ctx, Stage
+
+# Separated vocal stems keep faint bleed that crepe still finds a pitch in, so
+# frames this far below the song's loud vocal level count as silence. Relative
+# rather than absolute, so it holds however loud the song was mastered.
+SILENCE_BELOW_LOUD_DB = 25.0
+
+
+@on_release
+def unload_model() -> None:
+    """torchcrepe caches its model as attributes on its own infer function."""
+    torchcrepe = sys.modules.get("torchcrepe")
+    if torchcrepe is None:
+        return
+    for attr in ("model", "capacity"):
+        if hasattr(torchcrepe.infer, attr):
+            delattr(torchcrepe.infer, attr)
+
+
+def mute_silence(conf: np.ndarray, loudness: np.ndarray) -> None:
+    """Zero the confidence of frames quiet enough to be bleed, in place."""
+    conf[loudness < np.quantile(loudness, 0.9) - SILENCE_BELOW_LOUD_DB] = 0.0
+
+
+def track_pitch(vocals_path: Path, model: str, device: str):
+    import torchaudio
+    import torchcrepe
+
+    from ..audio_io import load_wav
+
+    waveform, sr = load_wav(vocals_path)
+    waveform = waveform.mean(0, keepdim=True)
+    waveform = torchaudio.functional.resample(waveform, sr, 16000)
+    f0, periodicity = torchcrepe.predict(
+        waveform, 16000, hop_length=160, model=model,
+        fmin=50.0, fmax=1100.0, device=device,
+        return_periodicity=True, batch_size=512)
+    f0 = f0[0].cpu().numpy()
+    conf = periodicity[0].cpu().numpy()
+    mute_silence(conf, torchcrepe.loudness.a_weighted(waveform, 16000, 160)[0].cpu().numpy())
+    times = np.arange(len(f0)) * 0.01
+    return times, f0, conf
+
+
+def _run(ctx: Ctx) -> None:
+    times, f0, conf = track_pitch(ctx.work / "vocals.wav",
+                                  ctx.cfg.crepe_model, ctx.cfg.device)
+    np.savez(ctx.work / "pitch.npz", times=times, f0=f0, conf=conf)
+
+
+def pitch_stage() -> Stage:
+    return Stage(name="pitch",
+                 outputs=lambda ctx: [ctx.work / "pitch.npz"],
+                 run=_run)

src/songtrace/stages/transcribe.py

@@ -0,0 +1,145 @@
+import difflib
+import json
+
+from ..lyrics import RefLyrics, alignment_token
+from ..pipeline import Ctx, Stage
+from ..whisper_client import TranscriptSegment, transcribe
+
+
+def vocal_sections(segments, min_gap: float = 6.0, pad: float = 1.0):
+    sections = []
+    for s in sorted(segments, key=lambda s: s.start):
+        if sections and s.start - sections[-1][1] < min_gap:
+            sections[-1][1] = max(sections[-1][1], s.end)
+        else:
+            sections.append([s.start, s.end])
+    return [(max(0.0, a - pad), b + pad) for a, b in sections]
+
+
+def _tokens(text: str) -> list[str]:
+    return [t for w in text.split() if (t := alignment_token(w))]
+
+
+def match_lyrics(segments, ref: RefLyrics):
+    heard, seg_of = [], []
+    for si, s in enumerate(segments):
+        for t in _tokens(s.text):
+            heard.append(t)
+            seg_of.append(si)
+    pairs = [(t, li) for w, li in zip(ref.words, ref.word_line_index)
+             if (t := alignment_token(w))]
+    expected = [t for t, _ in pairs]
+    line_of = [li for _, li in pairs]
+    matcher = difflib.SequenceMatcher(a=heard, b=expected)
+    return matcher, seg_of, line_of
+
+
+def lyrics_similarity(segments, ref: RefLyrics) -> float:
+    matcher, _, _ = match_lyrics(segments, ref)
+    return matcher.ratio()
+
+
+def _line_times(segments, matcher, seg_of, line_of) -> dict[int, tuple[float, float]]:
+    """For each reference line that was heard, the start of the first and the
+    end of the last transcript segment its words were heard in. Words in a
+    'replace' block are paired with heard words proportionally."""
+    times: dict[int, tuple[float, float]] = {}
+    for tag, ai1, ai2, bj1, bj2 in matcher.get_opcodes():
+        if tag not in ("equal", "replace"):
+            continue
+        for j in range(bj1, bj2):
+            seg = segments[seg_of[ai1 + (j - bj1) * (ai2 - ai1) // (bj2 - bj1)]]
+            a, b = times.get(line_of[j], (seg.start, seg.end))
+            times[line_of[j]] = (min(a, seg.start), max(b, seg.end))
+    return times
+
+
+def _unheard_runs(segments, ref: RefLyrics, unheard
+                  ) -> tuple[list[list[int]], list[list[tuple[float, float]]]]:
+    """Runs of reference lines with nothing heard for them, each with the
+    untranscribed singing between the heard lines either side of it."""
+    matcher, seg_of, line_of = match_lyrics(segments, ref)
+    times = _line_times(segments, matcher, seg_of, line_of)
+    alignable = set(line_of)
+    runs, spans, run, prev_end = [], [], [], 0.0
+
+    def close(next_start: float) -> None:
+        if run:
+            runs.append(list(run))
+            spans.append([(max(a, prev_end), min(b, next_start)) for a, b in unheard
+                          if a < next_start and b > prev_end])
+            run.clear()
+
+    for li in range(len(ref.lines)):
+        if li in times:
+            close(times[li][0])
+            prev_end = times[li][1]
+        elif li in alignable:
+            run.append(li)
+    close(float("inf"))
+    return runs, spans
+
+
+def recovered_spans(segments, ref: RefLyrics, unheard) -> list[tuple[float, float]]:
+    """The untranscribed singing that stands in for lines Whisper missed, so
+    alignment can place them there."""
+    return _merge_spans([sp for spans in _unheard_runs(segments, ref, unheard)[1]
+                         for sp in spans])
+
+
+def classify_lyrics_match(segments, ref: RefLyrics, pad: float = 1.0, unheard=()
+                          ) -> tuple[list[int], list[tuple[float, float]]]:
+    """Split reference lines into matched vs. dropped, and flag sung spans no
+    reference line explains.
+
+    dropped_lines: reference line indices covered only by 'insert' opcodes
+    (present in the lyrics, never heard), unless `unheard` (sung spans the
+    transcript has no text for) has singing between the heard lines either
+    side of them: then Whisper missed them, not the singer.
+
+    missing_spans: the padded, merged bounds of the heard segments behind
+    'delete' opcodes (heard, but matching no reference word). A segment can
+    also hold matched lines, so a span marks where to look, not words to
+    discard.
+    """
+    runs, run_spans = _unheard_runs(segments, ref, unheard)
+    dropped_lines = sorted(li for run, sp in zip(runs, run_spans) if not sp
+                           for li in run)
+
+    matcher, seg_of, _ = match_lyrics(segments, ref)
+    spans = []
+    for tag, ai1, ai2, _, _ in matcher.get_opcodes():
+        if tag != "delete":
+            continue
+        sis = [seg_of[i] for i in range(ai1, ai2)]
+        start = max(0.0, min(segments[si].start for si in sis) - pad)
+        end = max(segments[si].end for si in sis) + pad
+        spans.append((start, end))
+    return dropped_lines, _merge_spans(spans)
+
+
+def _merge_spans(spans: list[tuple[float, float]]) -> list[tuple[float, float]]:
+    merged: list[list[float]] = []
+    for a, b in sorted(spans):
+        if merged and a <= merged[-1][1]:
+            merged[-1][1] = max(merged[-1][1], b)
+        else:
+            merged.append([a, b])
+    return [tuple(s) for s in merged]
+
+
+def _run(ctx: Ctx) -> None:
+    segments = transcribe(ctx.cfg, ctx.work / "vocals.wav", ctx.inp.language)
+    (ctx.work / "transcript.json").write_text(json.dumps(
+        [{"start": s.start, "end": s.end, "text": s.text} for s in segments]))
+
+
+def transcribe_stage() -> Stage:
+    return Stage(name="transcribe",
+                 outputs=lambda ctx: [ctx.work / "transcript.json"],
+                 run=_run)
+
+
+def load_transcript(ctx: Ctx) -> list[TranscriptSegment]:
+    data = json.loads((ctx.work / "transcript.json").read_text())
+    return [TranscriptSegment(**d) for d in data]

src/songtrace/static/edit-model.js

@@ -0,0 +1,158 @@
+// Editing one line's notes. Every operation returns a new array and leaves
+// its input alone, so undo is just keeping the old one. Times are seconds,
+// snapped to the chart's beat grid as the chart itself will be. Notes carry
+// a client-side `id` so a selection survives reordering; it is never saved.
+
+const MIN_BEATS = 1;
+
+const spbOf = (grid) => 60 / (4 * grid.bpm);
+const gapOf = (grid) => grid.gap_ms / 1000;
+const byStart = (a, b) => a.start - b.start;
+
+let nextId = 1;
+export const newId = () => nextId++;
+
+export function beatOf(t, grid) {
+  return (t - gapOf(grid)) / spbOf(grid);
+}
+
+export function timeOf(beat, grid) {
+  return gapOf(grid) + beat * spbOf(grid);
+}
+
+export function snap(t, grid) {
+  return timeOf(Math.round(beatOf(t, grid)), grid);
+}
+
+// A note as the chart will have it: start on a beat, at least one beat long.
+function onGrid(n, grid) {
+  const start = snap(n.start, grid);
+  const beats = Math.max(MIN_BEATS, Math.round((n.end - n.start) / spbOf(grid)));
+  return { ...n, start, end: start + beats * spbOf(grid) };
+}
+
+export function withIds(notes) {
+  return notes.map(n => ({ ...n, id: n.id ?? newId() })).sort(byStart);
+}
+
+export function move(notes, ids, beats, semitones, grid) {
+  const spb = spbOf(grid);
+  return notes.map(n => {
+    if (!ids.has(n.id)) return n;
+    const g = onGrid(n, grid);
+    const shift = Math.max(beats * spb, -g.start);   // never before the song starts
+    return { ...g, start: g.start + shift, end: g.end + shift, pitch: n.pitch + semitones };
+  }).sort(byStart);
+}
+
+// Drag one edge of a note to time t; the other edge stays put.
+export function resize(notes, id, edge, t, grid) {
+  const spb = spbOf(grid);
+  return notes.map(n => {
+    if (n.id !== id) return n;
+    const g = onGrid(n, grid);
+    if (edge === "end") return { ...g, end: Math.max(snap(t, grid), g.start + spb) };
+    return { ...g, start: Math.max(0, Math.min(snap(t, grid), g.end - spb)) };
+  }).sort(byStart);
+}
+
+// Longer or shorter by whole beats, keeping the start.
+export function stretch(notes, ids, beats, grid) {
+  const spb = spbOf(grid);
+  return notes.map(n => {
+    if (!ids.has(n.id)) return n;
+    const g = onGrid(n, grid);
+    return { ...g, end: Math.max(g.end + beats * spb, g.start + spb) };
+  });
+}
+
+// In two at the beat nearest the middle; the second half holds the syllable.
+export function split(notes, id, grid) {
+  const i = notes.findIndex(n => n.id === id);
+  if (i < 0) return { notes, ids: [] };
+  const g = onGrid(notes[i], grid);
+  const beats = Math.round((g.end - g.start) / spbOf(grid));
+  if (beats < 2) return { notes, ids: [] };
+  const mid = g.start + Math.floor(beats / 2) * spbOf(grid);
+  const a = { ...g, end: mid };
+  const b = { ...g, id: newId(), start: mid, text: "~", low_confidence: false };
+  return { notes: [...notes.slice(0, i), a, b, ...notes.slice(i + 1)], ids: [a.id, b.id] };
+}
+
+// Into one with the note after it; a held "~" adds no text.
+export function merge(notes, id) {
+  const i = notes.findIndex(n => n.id === id);
+  if (i < 0 || i + 1 >= notes.length) return notes;
+  const a = notes[i];
+  const b = notes[i + 1];
+  const text = b.text.trim() === "~" ? a.text : a.text + b.text;
+  return [...notes.slice(0, i), { ...a, end: b.end, text }, ...notes.slice(i + 2)];
+}
+
+export function remove(notes, ids) {
+  return notes.filter(n => !ids.has(n.id));
+}
+
+export function insert(notes, t, pitch, grid) {
+  const start = Math.max(0, snap(t, grid));
+  const note = { id: newId(), start, end: start + 2 * spbOf(grid), pitch,
+                 text: "~", kind: ":", low_confidence: false };
+  return { notes: [...notes, note].sort(byStart), id: note.id };
+}
+
+// Applying a kind every selected note already has turns it back to normal.
+export function setKind(notes, ids, kind) {
+  const chosen = notes.filter(n => ids.has(n.id));
+  const to = chosen.length && chosen.every(n => n.kind === kind) ? ":" : kind;
+  return notes.map(n => (ids.has(n.id) ? { ...n, kind: to } : n));
+}
+
+// A syllable that starts a word keeps the space before it that marks it so.
+export function setText(notes, id, text) {
+  const clean = text.trim();
+  if (!clean) return notes;
+  return notes.map(n => {
+    if (n.id !== id) return n;
+    const lead = n.text.startsWith(" ") && !text.startsWith(" ") ? " " : "";
+    return { ...n, text: lead + (text.startsWith(" ") ? " " + clean : clean) };
+  });
+}
+
+// What the server stores for a line.
+export function toSaved(notes) {
+  return notes.map(n => ({ start: n.start, duration: n.end - n.start, pitch: n.pitch,
+                           text: n.text, kind: n.kind ?? ":" }));
+}
+
+export function history(initial) {
+  const past = [];
+  const future = [];
+  let present = initial;
+  return {
+    get present() { return present; },
+    get canUndo() { return past.length > 0; },
+    get canRedo() { return future.length > 0; },
+    push(next) {
+      if (next === present) return;
+      past.push(present);
+      future.length = 0;
+      present = next;
+    },
+    undo() {
+      if (past.length) { future.push(present); present = past.pop(); }
+      return present;
+    },
+    redo() {
+      if (future.length) { past.push(present); present = future.pop(); }
+      return present;
+    },
+  };
+}
+
+// Where a dragged line break lands: on a beat, but kept between the end of
+// the line before it and the start of the line it introduces.
+export function placeBreak(t, lo, hi, grid) {
+  const snapped = snap(t, grid);
+  if (hi < lo) return lo;
+  return Math.min(Math.max(snapped, lo), hi);
+}

src/songtrace/static/sheet.js

@@ -0,0 +1,951 @@
+// The note sheet: one lyric line at a time on a pitch-by-beat grid, the way
+// an UltraStar editor lays a song out, with the detected pitch drawn over
+// the notes so a wrong one stands out. The line on show can be edited.
+
+import * as edit from "./edit-model.js";
+
+const SVG = "http://www.w3.org/2000/svg";
+const NAMES = ["C", "C♯", "D", "D♯", "E", "F", "F♯", "G", "G♯", "A", "A♯", "B"];
+const BLACK = new Set([1, 3, 6, 8, 10]);
+const GUTTER = 46;        // px of note names left of the grid
+const PLOT_HEIGHT = 300;  // px; rows divide this between the pitches shown
+const CONTEXT = 0.75;     // seconds shown either side of the line
+const EDGE = 6;           // px from a note's end that grabs it for resizing
+const KINDS = { "*": "golden", F: "free", R: "rap", G: "golden-rap" };
+const KEYS_OPEN = "songtrace.sheet-keys";
+
+// The sheet's controls, grouped as an editor's reference card lists them.
+// "+" joins keys pressed together, " / " separates alternatives, and a
+// lowercase word is something done with the mouse rather than a key.
+export const SHORTCUTS = [
+  ["Select", [
+    ["click", "select a note"],
+    ["Shift+click", "add to the selection"],
+    ["Tab / Shift+Tab", "next, previous note"],
+    ["Esc", "clear the selection"]]],
+  ["Move", [
+    ["drag", "move in time and pitch"],
+    ["← / →", "a beat earlier, later"],
+    ["↑ / ↓", "a semitone up, down"],
+    ["Shift+↑ / Shift+↓", "an octave up, down"]]],
+  ["Length", [
+    ["drag an end", "resize"],
+    ["Shift+← / Shift+→", "a beat shorter, longer"]]],
+  ["Notes", [
+    ["double-click", "add a note, on empty space"],
+    ["S", "split in two"],
+    ["M", "merge with the next"],
+    ["Delete", "remove"]]],
+  ["Kind", [
+    ["G", "golden"],
+    ["F", "freestyle"],
+    ["R", "rap"],
+    ["G / F / R", "again: back to normal"]]],
+  ["Line break", [
+    ["drag a ↵ marker", "move it, between the lines it separates"],
+    ["double-click a ↵", "back to where songtrace puts it"]]],
+  ["Syllable", [
+    ["double-click", "edit, on a note"],
+    ["Enter", "edit the selected note"]]],
+  ["Line", [
+    ["Ctrl+Z", "undo"],
+    ["Ctrl+Shift+Z / Ctrl+Y", "redo"],
+    ["Ctrl+S", "save"],
+    ["P", "play"],
+    ["Page Up / Page Down", "previous, next line"],
+    ["?", "show or hide these keys"]]],
+];
+
+// "Shift+Tab / Esc" as key caps, with mouse actions left as words
+export function comboParts(combo) {
+  return combo.split(" / ").map(alt => alt.split("+").map(part => ({
+    text: part, key: !/^[a-z]/.test(part),
+  })));
+}
+
+const wrap = (n, d) => ((n % d) + d) % d;
+const mod12 = (p) => wrap(p, 12);
+
+// UltraStar pitch 0 is C4 (MIDI 60)
+export function noteName(pitch) {
+  return NAMES[mod12(pitch)] + (Math.floor((pitch + 60) / 12) - 1);
+}
+
+export function isBlackKey(pitch) {
+  return BLACK.has(mod12(pitch));
+}
+
+// The pitches to show: the line's notes with room around them, and never
+// less than an octave and a bit, so rows stay a consistent size to aim at.
+export function pitchRange(pitches, { pad = 3, min = 15 } = {}) {
+  if (!pitches.length) return { lo: -7, hi: 7 };
+  let lo = Math.min(...pitches) - pad;
+  let hi = Math.max(...pitches) + pad;
+  const short = min - (hi - lo + 1);
+  if (short > 0) {
+    lo -= Math.floor(short / 2);
+    hi += Math.ceil(short / 2);
+  }
+  return { lo, hi };
+}
+
+// UltraStar beats between t0 and t1 on the chart's grid. A beat is a quarter
+// of the #BPM beat; weight 2 marks every 16th, 1 every 4th, as editors do.
+export function beatLines(t0, t1, grid) {
+  const spb = 60 / (4 * grid.bpm);
+  const gap = grid.gap_ms / 1000;
+  const out = [];
+  for (let k = Math.ceil((t0 - gap) / spb); gap + k * spb <= t1; k++) {
+    const weight = wrap(k, 16) === 0 ? 2 : wrap(k, 4) === 0 ? 1 : 0;
+    out.push({ t: gap + k * spb, beat: k, weight });
+  }
+  return out;
+}
+
+// The seconds a line occupies, from its notes and the words it was aligned to.
+export function lineSpan(line) {
+  const ts = [...line.notes.flatMap(n => [n.start, n.end]),
+              ...line.words.flatMap(w => [w.start, w.end])];
+  return ts.length ? { start: Math.min(...ts), end: Math.max(...ts) } : null;
+}
+
+function el(name, attrs = {}, parent = null) {
+  const node = document.createElementNS(SVG, name);
+  for (const [k, v] of Object.entries(attrs)) node.setAttribute(k, v);
+  if (parent) parent.append(node);
+  return node;
+}
+
+function div(cls, text = null) {
+  const node = document.createElement("div");
+  node.className = cls;
+  if (text !== null) node.textContent = text;
+  return node;
+}
+
+export function createSheet(root, { seek, playLine, onSaved }) {
+  const button = (label, title, onClick, cls = "action") => {
+    const b = document.createElement("button");
+    b.type = "button";
+    b.className = cls;
+    b.textContent = label;
+    b.title = title;
+    b.addEventListener("click", onClick);
+    return b;
+  };
+  const title = div("sheet-title");
+  const badges = div("sheet-badges");
+  const prev = button("◀ PREV", "previous line (Page Up)", () => page(-1));
+  const next = button("NEXT ▶", "next line (Page Down)", () => page(1));
+  const nav = div("sheet-nav");
+  const keysButton = button("KEYS ?", "keyboard shortcuts (?)", () => toggleKeys());
+  keysButton.setAttribute("aria-expanded", "false");
+  nav.append(prev, title, next, badges, keysButton);
+
+  const tools = {
+    undo: button("UNDO", "Ctrl+Z", () => undo()),
+    redo: button("REDO", "Ctrl+Shift+Z", () => redo()),
+    split: button("SPLIT", "split the selected note (S)", () => splitSelected()),
+    merge: button("MERGE", "merge with the next note (M)", () => mergeSelected()),
+    remove: button("DELETE", "delete the selected notes (Delete)", () => removeSelected()),
+    golden: button("GOLDEN", "golden note (G)", () => kind("*")),
+    free: button("FREESTYLE", "freestyle note (F)", () => kind("F")),
+    rap: button("RAP", "rap note (R)", () => kind("R")),
+    play: button("▶ LINE", "play this line (P)", () => playCurrent()),
+    discard: button("DISCARD", "drop unsaved changes to this line", () => discard()),
+    revert: button("REVERT", "go back to the generated notes for this line", () => revert()),
+    save: button("SAVE LINE", "Ctrl+S", () => save(), "action sheet-save"),
+  };
+  const toolbar = div("sheet-tools");
+  const group = (...items) => { const g = div("sheet-tool-group"); g.append(...items); return g; };
+  const status = div("sheet-status");
+  status.setAttribute("role", "status");
+  toolbar.append(group(tools.undo, tools.redo),
+                 group(tools.split, tools.merge, tools.remove),
+                 group(tools.golden, tools.free, tools.rap),
+                 group(tools.play), status,
+                 group(tools.discard, tools.revert, tools.save));
+
+  const plot = div("sheet-plot");
+  plot.tabIndex = 0;
+  plot.setAttribute("aria-label", "note sheet: select notes and edit them with the mouse or keyboard");
+  const svg = el("svg", { class: "sheet-svg" });
+  const playhead = div("sheet-playhead");
+  playhead.hidden = true;
+  plot.append(svg, playhead);
+  const syllables = div("sheet-syllables");
+  const words = div("sheet-words");
+  const help = div("sheet-help", "Press ? for keyboard shortcuts.");
+  const keys = div("sheet-keys");
+  keys.id = "sheet-keys";
+  keysButton.setAttribute("aria-controls", keys.id);
+  for (const [group, entries] of SHORTCUTS) {
+    const section = div("sheet-keys-group");
+    const heading = div("sheet-keys-head", group);
+    const list = document.createElement("dl");
+    for (const [combo, action] of entries) {
+      const dt = document.createElement("dt");
+      comboParts(combo).forEach((alt, i) => {
+        if (i) dt.append(" / ");
+        alt.forEach((part, j) => {
+          if (j) dt.append("+");
+          const node = document.createElement(part.key ? "kbd" : "span");
+          node.textContent = part.text;
+          dt.append(node);
+        });
+      });
+      const dd = document.createElement("dd");
+      dd.textContent = action;
+      list.append(dt, dd);
+    }
+    section.append(heading, list);
+    keys.append(section);
+  }
+  const stale = div("sheet-stale");
+  const gridBar = div("sheet-grid");
+  const field = (label, step, unit) => {
+    const wrap = document.createElement("label");
+    wrap.className = "sheet-grid-field";
+    const input = document.createElement("input");
+    input.type = "number";
+    input.step = step;
+    input.min = "0";
+    wrap.append(label, input);
+    if (unit) wrap.append(unit);
+    return { wrap, input };
+  };
+  const bpmField = field("BPM", "0.01");
+  const gapField = field("GAP", "1", "ms");
+  const gridSource = div("sheet-grid-source");
+  const gridTools = {
+    double: button("×2", "double the BPM", () => tryGrid({ bpm: grid().bpm * 2 })),
+    half: button("÷2", "halve the BPM", () => tryGrid({ bpm: grid().bpm / 2 })),
+    earlier: button("−10", "GAP 10ms earlier", () => tryGrid({ gap_ms: grid().gap_ms - 10 })),
+    later: button("+10", "GAP 10ms later", () => tryGrid({ gap_ms: grid().gap_ms + 10 })),
+    align: button("ALIGN TO NOTE", "move GAP the least that puts the selected note on a beat",
+                  () => alignToNote()),
+    cancel: button("CANCEL", "drop the BPM and GAP being tried", () => { gridDraft = null; render(); }),
+    reset: button("RESET", "back to the BPM songtrace chose, with GAP at the first note",
+                  () => resetGrid()),
+    apply: button("APPLY", "chart the song on this BPM and GAP", () => applyGrid(),
+                  "action sheet-save"),
+  };
+  const gridHead = div("sheet-grid-head", "GRID");
+  gridBar.append(gridHead, bpmField.wrap, gridTools.double, gridTools.half,
+                 gapField.wrap, gridTools.earlier, gridTools.later, gridTools.align,
+                 gridSource, gridTools.cancel, gridTools.reset, gridTools.apply);
+  for (const [f, key] of [[bpmField, "bpm"], [gapField, "gap_ms"]]) {
+    f.input.addEventListener("input", () => {
+      const v = Number(f.input.value);
+      if (f.input.value !== "" && Number.isFinite(v) && v >= 0 && (key === "gap_ms" || v > 0)) {
+        tryGrid({ [key]: v }, f.input);
+      }
+    });
+  }
+  root.replaceChildren(nav, stale, gridBar, toolbar, keys, plot, syllables, words, help);
+
+  // stays as the person left it, across lines, songs and visits
+  function showKeys(open) {
+    keys.hidden = !open;
+    help.hidden = open;
+    keysButton.setAttribute("aria-expanded", String(open));
+    try { localStorage.setItem(KEYS_OPEN, open ? "1" : ""); } catch {}
+  }
+  function toggleKeys() {
+    showKeys(keys.hidden);
+  }
+  let keysOpen = false;
+  try { keysOpen = !!localStorage.getItem(KEYS_OPEN); } catch {}
+  showKeys(keysOpen);
+
+  let review = null;
+  let curve = null;
+  let index = null;
+  let jobId = null;
+  let view = null;        // what the last render laid out: window and scale
+  let layout = null;      // window and pitch range, kept steady while editing
+  let hist = null;        // the current line's notes, with undo
+  let baseline = null;    // what the line holds on the server
+  let preview = null;     // notes mid-drag, not yet in the history
+  let breakPreview = null;  // a break mid-drag: { which, t }
+  let selected = new Set();
+  let drag = null;
+  let saving = false;
+
+  const visible = () => review.lines.filter(l => !l.dropped && lineSpan(l));
+  // the line being edited: its notes and the breaks either side of it, as
+  // one state so undo covers both. A break is its time, undefined where there
+  // is none to move, or null when it is to go back to automatic.
+  const notes = () => preview ?? hist?.present.notes ?? [];
+  const dirty = () => !!hist && hist.present !== baseline;
+  let gridDraft = null;   // BPM and GAP being tried out, not yet applied
+  // the grid being drawn and snapped to: the one being tried out, if any
+  const grid = () => gridDraft ?? review?.grid;
+  // notes snap to the grid, so they wait while a new one is being tried
+  const canEdit = () => !!review?.grid && !gridDraft && !saving;
+
+  function say(text, error = false) {
+    status.textContent = text;
+    status.classList.toggle("sheet-status-error", error);
+  }
+
+  // the window and pitch range that hold the line, grown (never shrunk while
+  // editing) so rows do not jump under the pointer
+  function fit(reset) {
+    const line = review.lines[index];
+    const ts = [...notes().flatMap(n => [n.start, n.end]),
+                ...line.words.flatMap(w => [w.start, w.end])];
+    const span = ts.length ? { start: Math.min(...ts), end: Math.max(...ts) } : lineSpan(line);
+    const range = pitchRange(notes().map(n => n.pitch));
+    const want = { t0: span.start - CONTEXT, t1: span.end + CONTEXT, ...range };
+    // the breaks either side are part of the line's page, so they stay on it
+    for (const slot of breakSlots()) {
+      const t = breakTime(slot);
+      want.t0 = Math.min(want.t0, t - 0.3);
+      want.t1 = Math.max(want.t1, t + 0.3);
+    }
+    layout = reset || !layout ? want : {
+      t0: Math.min(layout.t0, want.t0), t1: Math.max(layout.t1, want.t1),
+      lo: Math.min(layout.lo, want.lo), hi: Math.max(layout.hi, want.hi),
+    };
+  }
+
+  // edits whose line's lyrics have since changed: kept, not applied, until
+  // the person who made them decides
+  function paintStale() {
+    const items = review?.stale ?? [];
+    stale.hidden = !items.length;
+    stale.replaceChildren();
+    if (!items.length) return;
+    stale.append(div("sheet-stale-head",
+      `${items.length} edited line${items.length === 1 ? " was" : "s were"} set aside ` +
+      "because the lyrics changed:"));
+    items.forEach((item, n) => {
+      const row = div("sheet-stale-row");
+      row.append(div("sheet-stale-text", `"${item.text}"`),
+                 button("DISCARD", "throw this edit away", () => discardStale(n)));
+      stale.append(row);
+    });
+  }
+
+  async function discardStale(n) {
+    const resp = await fetch(`/api/jobs/${jobId}/stale/${n}`, { method: "DELETE" });
+    if (!resp.ok) { say(`error ${resp.status}`, true); return; }
+    review = await resp.json();
+    paintStale();
+    onSaved(review);
+  }
+
+  function open(i) {
+    index = i;
+    const line = review.lines[i];
+    const lines = visible();
+    const at = lines.findIndex(l => l.index === i);
+    const breakBefore = (l) => review.breaks?.find(b => b.line === l?.index)?.time;
+    baseline = {
+      notes: edit.withIds(line.notes.map(n => ({ ...n, kind: n.kind ?? ":" }))),
+      before: at > 0 ? breakBefore(line) : undefined,
+      after: breakBefore(lines[at + 1]),
+    };
+    hist = edit.history(baseline);
+    breakPreview = null;
+    preview = null;
+    selected = new Set();
+    say("");
+    fit(true);
+    paintStale();
+    render();
+  }
+
+  // asked for by the person using the sheet, so it may cost them their edits
+  function goTo(i) {
+    if (!review || i === index) return;
+    if (dirty() && !confirm("Discard unsaved changes to this line?")) return;
+    open(i);
+  }
+
+  function page(step) {
+    const lines = visible();
+    const at = lines.findIndex(l => l.index === index);
+    const to = lines[Math.min(Math.max(at + step, 0), lines.length - 1)];
+    if (to) goTo(to.index);
+  }
+
+  function change(next, keep = selected) {
+    hist.push({ ...hist.present, notes: next });
+    selected = new Set([...keep].filter(id => next.some(n => n.id === id)));
+    fit(false);
+    render();
+  }
+
+  function changeBreak(which, t) {
+    if (hist.present[which] === t) return;
+    hist.push({ ...hist.present, [which]: t });
+    render();
+  }
+
+  // the breaks either side of the line, each with the gap it may move in:
+  // from the end of the line before it to the start of the line after
+  function breakSlots() {
+    const ns = notes();
+    if (!hist || !ns.length) return [];
+    const lines = visible();
+    const at = lines.findIndex(l => l.index === index);
+    const prev = lines[at - 1];
+    const next = lines[at + 1];
+    const slots = [];
+    if (prev?.notes.length && hist.present.before !== undefined) {
+      slots.push({ which: "before", line: index,
+                   lo: Math.max(...prev.notes.map(n => n.end)), hi: ns[0].start });
+    }
+    if (next?.notes.length && hist.present.after !== undefined) {
+      slots.push({ which: "after", line: next.index,
+                   lo: Math.max(...ns.map(n => n.end)), hi: Math.min(...next.notes.map(n => n.start)) });
+    }
+    return slots;
+  }
+
+  // where a break is drawn; one going back to automatic is shown mid-gap,
+  // roughly where it will land
+  function breakTime(slot) {
+    const v = breakPreview?.which === slot.which ? breakPreview.t : hist.present[slot.which];
+    const t = v === null ? (slot.lo + slot.hi) / 2 : v;
+    return Math.min(Math.max(t, slot.lo), Math.max(slot.hi, slot.lo));
+  }
+
+  const undo = () => { if (hist?.canUndo) { hist.undo(); fit(false); render(); } };
+  const redo = () => { if (hist?.canRedo) { hist.redo(); fit(false); render(); } };
+  const one = () => (selected.size === 1 ? [...selected][0] : null);
+
+  function splitSelected() {
+    if (one() === null || !grid()) return;
+    const out = edit.split(notes(), one(), grid());
+    if (out.notes !== notes()) change(out.notes, new Set([out.ids[0]]));
+  }
+  function mergeSelected() {
+    if (one() !== null) change(edit.merge(notes(), one()));
+  }
+  function removeSelected() {
+    if (selected.size) change(edit.remove(notes(), selected), new Set());
+  }
+  function kind(k) {
+    if (selected.size) change(edit.setKind(notes(), selected, k));
+  }
+  function playCurrent() {
+    if (!layout) return;
+    const ns = notes();
+    const start = ns.length ? ns[0].start : layout.t0 + CONTEXT;
+    const end = ns.length ? Math.max(...ns.map(n => n.end)) : layout.t1 - CONTEXT;
+    playLine(Math.max(0, start - 0.3), end + 0.2);
+  }
+
+  function discard() {
+    if (!dirty()) return;
+    open(index);
+  }
+
+  // a change saved to the server, which answers with the refreshed review
+  async function send(path, method, body, busy, done) {
+    saving = true;
+    render();
+    say(busy);
+    try {
+      const resp = await fetch(`/api/jobs/${jobId}/${path}`, {
+        method, headers: { "Content-Type": "application/json" },
+        body: body ? JSON.stringify(body) : undefined,
+      });
+      if (!resp.ok) {
+        const err = await resp.json().catch(() => ({}));
+        say(err.detail || `error ${resp.status}`, true);
+        return false;
+      }
+      const data = await resp.json();
+      const at = index;
+      review = data;
+      gridDraft = null;
+      open(at);
+      say(done);
+      onSaved(data);
+      return true;
+    } catch {
+      say("could not reach songtrace", true);
+      return false;
+    } finally {
+      saving = false;
+      render();
+    }
+  }
+
+  // only what changed: a moved break alone must not mark the line edited
+  async function save() {
+    if (!dirty() || saving) return;
+    const state = hist.present;
+    const lines = visible();
+    const next = lines[lines.findIndex(l => l.index === index) + 1];
+    const moved = {};
+    if (state.before !== baseline.before) moved[index] = state.before;
+    if (state.after !== baseline.after && next) moved[next.index] = state.after;
+    if (state.notes !== baseline.notes &&
+        !await send(`lines/${index}`, "PUT", { notes: edit.toSaved(state.notes) }, "saving…", "saved")) {
+      return;
+    }
+    if (Object.keys(moved).length) await send("breaks", "PUT", moved, "saving…", "saved");
+  }
+
+  function revert() {
+    if (!review.lines[index].edited || saving) return;
+    if (!confirm("Go back to the generated notes for this line? Your edit is lost.")) return;
+    send(`lines/${index}`, "DELETE", null, "reverting…", "reverted to the generated notes");
+  }
+
+  // redraws on the trial grid straight away; nothing is saved until APPLY
+  function tryGrid(change, typing = null) {
+    const next = { ...grid(), ...change };
+    next.gap_ms = Math.max(0, next.gap_ms);
+    const same = review.grid && next.bpm === review.grid.bpm && next.gap_ms === review.grid.gap_ms;
+    gridDraft = same ? null : next;
+    render(typing);
+  }
+
+  function alignToNote() {
+    const note = notes().find(n => selected.has(n.id));
+    if (!note) return;
+    const g = grid();
+    const spbMs = 60000 / (4 * g.bpm);
+    const atMs = note.start * 1000;
+    const offset = (atMs - g.gap_ms) - Math.round((atMs - g.gap_ms) / spbMs) * spbMs;
+    tryGrid({ gap_ms: Math.round((g.gap_ms + offset) * 100) / 100 });
+  }
+
+  async function applyGrid() {
+    if (!gridDraft || saving) return;
+    if (dirty()) { say("save or discard this line's changes first", true); return; }
+    await send("grid", "PUT", gridDraft, "charting on the new grid…", "grid applied");
+  }
+
+  async function resetGrid() {
+    if (!review.grid_edited || saving) return;
+    if (dirty()) { say("save or discard this line's changes first", true); return; }
+    await send("grid", "DELETE", null, "resetting the grid…",
+               "grid reset to the BPM songtrace chose");
+  }
+
+  function paintGrid(typing) {
+    const g = grid();
+    gridBar.hidden = !review.grid;
+    if (!g) return;
+    const round = (v, d) => String(Math.round(v * 10 ** d) / 10 ** d);
+    // the field being typed in keeps what was typed, half-finished or not
+    if (typing !== bpmField.input) bpmField.input.value = round(g.bpm, 2);
+    if (typing !== gapField.input) gapField.input.value = round(g.gap_ms, 2);
+    gridSource.textContent = gridDraft ? "not applied"
+      : review.grid_edited ? "set in the editor"
+      : review.auto_bpm ? "songtrace's choice" : "";
+    gridSource.classList.toggle("sheet-grid-pending", !!gridDraft);
+    gridTools.align.disabled = saving || selected.size !== 1;
+    gridTools.cancel.disabled = !gridDraft || saving;
+    gridTools.apply.disabled = !gridDraft || saving;
+    gridTools.reset.disabled = !review.grid_edited || !!gridDraft || saving;
+    for (const b of [gridTools.double, gridTools.half, gridTools.earlier, gridTools.later]) {
+      b.disabled = saving;
+    }
+  }
+
+  function render(typing = null) {
+    if (!review || index === null) return;
+    const line = review.lines[index];
+    const { t0, t1, lo, hi } = layout;
+    const width = Math.max(plot.clientWidth, 320);
+    const rowH = PLOT_HEIGHT / (hi - lo + 1);
+    const x = (t) => GUTTER + ((t - t0) / (t1 - t0)) * (width - GUTTER);
+    const y = (p) => (hi - p) * rowH;   // top of the row for pitch p
+    view = { t0, t1, x, width, rowH, hi,
+             time: (px) => t0 + ((px - GUTTER) / (width - GUTTER)) * (t1 - t0),
+             pitch: (py) => hi - Math.floor(py / rowH) };
+
+    svg.setAttribute("viewBox", `0 0 ${width} ${PLOT_HEIGHT}`);
+    svg.setAttribute("width", width);
+    svg.setAttribute("height", PLOT_HEIGHT);
+    svg.replaceChildren();
+
+    const rows = el("g", { class: "sheet-rows" }, svg);
+    for (let p = lo; p <= hi; p++) {
+      el("rect", { x: GUTTER, y: y(p), width: width - GUTTER, height: rowH,
+                   class: isBlackKey(p) ? "sheet-row sheet-row-black" : "sheet-row" }, rows);
+      if (mod12(p) === 0) {
+        el("line", { x1: GUTTER, x2: width, y1: y(p) + rowH, y2: y(p) + rowH,
+                     class: "sheet-octave" }, rows);
+      }
+      // every C names its octave; the naturals between get a name when
+      // there is room for it
+      if (mod12(p) === 0 || (rowH >= 16 && !isBlackKey(p))) {
+        const label = el("text", { x: GUTTER - 6, y: y(p) + rowH / 2,
+                                   class: mod12(p) === 0 ? "sheet-key sheet-key-c" : "sheet-key" },
+                         rows);
+        label.textContent = noteName(p);
+      }
+    }
+
+    if (grid()) {
+      const beats = el("g", { class: "sheet-beats" }, svg);
+      const spbPx = x(60 / (4 * grid().bpm)) - x(0);
+      for (const b of beatLines(t0, t1, grid())) {
+        if (b.weight === 0 && spbPx < 10) continue;
+        el("line", { x1: x(b.t), x2: x(b.t), y1: 0, y2: PLOT_HEIGHT,
+                     class: `sheet-beat sheet-beat-${b.weight}` }, beats);
+      }
+    }
+
+    const layer = el("g", { class: "sheet-notes" }, svg);
+    const pad = Math.min(2, rowH * 0.12);
+    const drawNote = (n, current) => {
+      const cls = ["sheet-note", `sheet-note-${KINDS[n.kind] ?? "normal"}`];
+      if (!current) cls.push("sheet-note-context");
+      if (current && n.low_confidence) cls.push("sheet-note-low");
+      if (current && selected.has(n.id)) cls.push("sheet-note-selected");
+      const rect = el("rect", { x: x(n.start), y: y(n.pitch) + pad,
+                                width: Math.max(x(n.end) - x(n.start), 2), height: rowH - 2 * pad,
+                                rx: Math.min(4, rowH / 3), class: cls.join(" ") }, layer);
+      if (current) rect.dataset.id = n.id;
+      el("title", {}, rect).textContent = `${n.text.trim() || "~"} · ${noteName(n.pitch)}`;
+    };
+    for (const l of review.lines) {
+      if (l.dropped || l.index === index) continue;
+      for (const n of l.notes) if (n.end >= t0 && n.start <= t1) drawNote(n, false);
+    }
+    for (const n of notes()) drawNote(n, true);
+
+    const marks = el("g", { class: "sheet-breaks" }, svg);
+    for (const slot of breakSlots()) {
+      const t = breakTime(slot);
+      const value = hist.present[slot.which];
+      const byHand = value !== null &&
+        (value !== baseline[slot.which] || review.breaks?.find(b => b.line === slot.line)?.moved);
+      const cls = `sheet-break${byHand ? " sheet-break-moved" : ""}`;
+      el("line", { x1: x(t), x2: x(t), y1: 0, y2: PLOT_HEIGHT, class: cls }, marks);
+      el("text", { x: x(t) + 3, y: 11, class: `${cls} sheet-break-label` }, marks)
+        .textContent = "↵";
+    }
+
+    syllables.replaceChildren(...notes().map(n => {
+      const s = div("sheet-syllable" + (selected.has(n.id) ? " sheet-syllable-selected" : ""),
+                    n.text.trim() || "~");
+      s.style.left = `${x(n.start)}px`;
+      s.dataset.id = n.id;
+      return s;
+    }));
+
+    // over the notes: the curve matters most where it agrees with one
+    if (curve) {
+      const g = el("g", { class: "sheet-curve" }, svg);
+      const from = Math.max(0, Math.floor((t0 - curve.start) / curve.step));
+      const to = Math.min(curve.pitch.length, Math.ceil((t1 - curve.start) / curve.step));
+      let pts = [];
+      const flush = () => {
+        if (pts.length > 1) el("polyline", { points: pts.join(" ") }, g);
+        pts = [];
+      };
+      for (let k = from; k < to; k++) {
+        const p = curve.pitch[k];
+        if (p === null || p < lo - 0.5 || p > hi + 0.5) { flush(); continue; }
+        pts.push(`${x(curve.start + k * curve.step).toFixed(1)},${(y(p) + rowH / 2).toFixed(1)}`);
+      }
+      flush();
+    }
+
+    words.replaceChildren(...line.words.map(w => {
+      const node = div("sheet-word", w.text);
+      node.style.left = `${x(w.start)}px`;
+      node.style.width = `${Math.max(x(w.end) - x(w.start), 2)}px`;
+      return node;
+    }));
+
+    const lines = visible();
+    const at = lines.findIndex(l => l.index === index);
+    title.textContent = `LINE ${at + 1} / ${lines.length}`;
+    prev.disabled = at <= 0;
+    next.disabled = at >= lines.length - 1;
+    const tags = [];
+    if (dirty()) tags.push(["unsaved", "sheet-badge-dirty"]);
+    if (line.edited) tags.push(["edited", "sheet-badge-edited"]);
+    if (notes().some(n => n.low_confidence)) tags.push(["low confidence", "sheet-badge-low"]);
+    badges.replaceChildren(...tags.map(([text, cls]) => div(`sheet-badge ${cls}`, text)));
+
+    paintTools();
+    paintGrid(typing);
+  }
+
+  function paintSelection() {
+    for (const node of root.querySelectorAll("[data-id]")) {
+      const on = selected.has(Number(node.dataset.id));
+      node.classList.toggle(node.tagName === "rect" ? "sheet-note-selected"
+                                                     : "sheet-syllable-selected", on);
+    }
+    paintTools();
+    paintGrid();
+  }
+
+  function paintTools() {
+    const line = review.lines[index];
+    const editable = canEdit();
+    tools.undo.disabled = !editable || !hist.canUndo;
+    tools.redo.disabled = !editable || !hist.canRedo;
+    tools.split.disabled = tools.merge.disabled = !editable || one() === null;
+    for (const b of [tools.remove, tools.golden, tools.free, tools.rap]) {
+      b.disabled = !editable || !selected.size;
+    }
+    tools.discard.disabled = !dirty() || saving;
+    tools.save.disabled = !dirty() || saving;
+    tools.revert.disabled = !line.edited || saving;
+  }
+
+  // --- pointer -------------------------------------------------------------
+
+  function hit(e) {
+    const box = plot.getBoundingClientRect();
+    const px = e.clientX - box.left;
+    const py = e.clientY - box.top;
+    // by geometry, not the event's target: a render replaces the elements
+    // under the pointer, and the topmost note drawn wins
+    if (canEdit()) {
+      const brk = breakSlots().find(s => Math.abs(px - view.x(breakTime(s))) <= 5);
+      if (brk) return { px, py, note: null, brk, mode: "break" };
+    }
+    const pitch = view.pitch(py);
+    const note = [...notes()].reverse().find(n => n.pitch === pitch &&
+      px >= view.x(n.start) - 1 && px <= view.x(n.end) + 1) ?? null;
+    let mode = null;
+    if (note) {
+      const left = view.x(note.start);
+      const right = view.x(note.end);
+      mode = right - left > 3 * EDGE && px >= right - EDGE ? "end"
+           : right - left > 3 * EDGE && px <= left + EDGE ? "start" : "move";
+    }
+    return { px, py, note, brk: null, mode };
+  }
+
+  plot.addEventListener("pointermove", (e) => {
+    if (!view) return;
+    if (!drag) {
+      const { note, brk, mode } = hit(e);
+      plot.style.cursor = brk ? "col-resize"
+                        : !note || !canEdit() ? "crosshair"
+                        : mode === "move" ? "grab" : "ew-resize";
+      return;
+    }
+    const box = plot.getBoundingClientRect();
+    const px = e.clientX - box.left;
+    const py = e.clientY - box.top;
+    if (Math.abs(px - drag.px) + Math.abs(py - drag.py) > 3) drag.moved = true;
+    if (drag.moved && drag.brk) {
+      const { which, lo, hi } = drag.brk;
+      breakPreview = { which, t: edit.placeBreak(view.time(px), lo, hi, grid()) };
+      render();
+      return;
+    }
+    if (!drag.moved || !drag.note) return;
+    if (drag.mode === "move") {
+      const spbPx = view.x(60 / (4 * grid().bpm)) - view.x(0);
+      const beats = Math.round((px - drag.px) / spbPx);
+      const semis = Math.round((drag.py - py) / view.rowH);
+      preview = edit.move(drag.base, selected, beats, semis, grid());
+    } else {
+      preview = edit.resize(drag.base, drag.note.id, drag.mode, view.time(px), grid());
+    }
+    render();
+  });
+
+  plot.addEventListener("pointerdown", (e) => {
+    if (!view || e.button !== 0) return;
+    // the browser's own focus handling would otherwise take focus off the
+    // sheet, and with it the keyboard
+    e.preventDefault();
+    plot.focus();
+    const { px, py, note, brk, mode } = hit(e);
+    if (px < GUTTER) return;
+    if (brk) plot.setPointerCapture(e.pointerId);
+    if (note && canEdit()) {
+      if (e.shiftKey) {
+        selected = new Set(selected);
+        if (selected.has(note.id)) selected.delete(note.id); else selected.add(note.id);
+      } else if (!selected.has(note.id)) {
+        selected = new Set([note.id]);
+      }
+      plot.setPointerCapture(e.pointerId);
+      plot.style.cursor = mode === "move" ? "grabbing" : "ew-resize";
+      paintSelection();
+    }
+    drag = { px, py, note, brk, mode, base: notes(), moved: false };
+  });
+
+  const endDrag = (e, cancelled) => {
+    if (!drag) return;
+    const d = drag;
+    drag = null;
+    if (breakPreview) {
+      const { which, t } = breakPreview;
+      breakPreview = null;
+      if (cancelled) render(); else changeBreak(which, t);
+    } else if (preview) {
+      const next = preview;
+      preview = null;
+      if (cancelled) render(); else change(next);
+    } else if (!d.moved && !d.note && !d.brk && !cancelled) {
+      selected = new Set();
+      render();
+      seek(view.time(d.px));
+    }
+    if (plot.hasPointerCapture?.(e.pointerId)) plot.releasePointerCapture(e.pointerId);
+  };
+  plot.addEventListener("pointerup", (e) => endDrag(e, false));
+  plot.addEventListener("pointercancel", (e) => endDrag(e, true));
+
+  plot.addEventListener("dblclick", (e) => {
+    if (!view || !canEdit()) return;
+    const { px, py, note, brk } = hit(e);
+    if (px < GUTTER) return;
+    if (brk) { changeBreak(brk.which, null); return; }   // back to automatic
+    if (note) { editText(note.id); return; }
+    const out = edit.insert(notes(), view.time(px), view.pitch(py), grid());
+    change(out.notes, new Set([out.id]));
+    editText(out.id);
+  });
+
+  // --- syllable text -------------------------------------------------------
+
+  function editText(id) {
+    const note = notes().find(n => n.id === id);
+    if (!note) return;
+    const input = document.createElement("input");
+    input.className = "sheet-text-input";
+    input.value = note.text.trim();
+    input.style.left = `${view.x(note.start)}px`;
+    input.setAttribute("aria-label", "syllable");
+    syllables.append(input);
+    input.focus();
+    input.select();
+    let done = false;
+    const finish = (commit) => {
+      if (done) return;
+      done = true;
+      const value = input.value;
+      input.remove();
+      if (commit) {
+        const next = edit.setText(notes(), id, value);
+        if (next !== notes()) change(next);
+      }
+      plot.focus();
+    };
+    input.addEventListener("keydown", (e) => {
+      e.stopPropagation();
+      if (e.key === "Enter") finish(true);
+      else if (e.key === "Escape") finish(false);
+    });
+    input.addEventListener("blur", () => finish(true));
+  }
+
+  syllables.addEventListener("dblclick", (e) => {
+    const id = e.target.dataset?.id;
+    if (id) editText(Number(id));
+  });
+
+  // --- keyboard ------------------------------------------------------------
+
+  plot.addEventListener("keydown", (e) => {
+    if (!view) return;
+    const ctrl = e.ctrlKey || e.metaKey;
+    const key = e.key;
+    const handled = () => { e.preventDefault(); e.stopPropagation(); };
+    if (ctrl && key.toLowerCase() === "s") { handled(); save(); return; }
+    if (ctrl && key.toLowerCase() === "z") { handled(); e.shiftKey ? redo() : undo(); return; }
+    if (ctrl && key.toLowerCase() === "y") { handled(); redo(); return; }
+    if (key === "PageUp") { handled(); page(-1); return; }
+    if (key === "PageDown") { handled(); page(1); return; }
+    if (ctrl || e.altKey || !canEdit()) return;
+    const ns = notes();
+    if (key === "Tab") {
+      handled();
+      if (!ns.length) return;
+      const at = ns.findIndex(n => selected.has(n.id));
+      const to = at < 0 ? (e.shiftKey ? ns.length - 1 : 0)
+                        : (at + (e.shiftKey ? -1 : 1) + ns.length) % ns.length;
+      selected = new Set([ns[to].id]);
+      render();
+      return;
+    }
+    if (key === "?") { handled(); toggleKeys(); return; }
+    if (key === "Escape") {
+      handled();
+      if (!keys.hidden) showKeys(false);
+      else { selected = new Set(); render(); }
+      return;
+    }
+    if (key.toLowerCase() === "p") { handled(); playCurrent(); return; }
+    if (!selected.size) return;
+    const arrows = { ArrowLeft: -1, ArrowRight: 1 };
+    if (key in arrows) {
+      handled();
+      change(e.shiftKey ? edit.stretch(ns, selected, arrows[key], grid())
+                        : edit.move(ns, selected, arrows[key], 0, grid()));
+    } else if (key === "ArrowUp" || key === "ArrowDown") {
+      handled();
+      change(edit.move(ns, selected, 0, (key === "ArrowUp" ? 1 : -1) * (e.shiftKey ? 12 : 1), grid()));
+    } else if (key === "Delete" || key === "Backspace") {
+      handled(); removeSelected();
+    } else if (key === "Enter" && one() !== null) {
+      handled(); editText(one());
+    } else if (key.toLowerCase() === "s") {
+      handled(); splitSelected();
+    } else if (key.toLowerCase() === "m") {
+      handled(); mergeSelected();
+    } else if ({ g: "*", f: "F", r: "R" }[key.toLowerCase()]) {
+      handled(); kind({ g: "*", f: "F", r: "R" }[key.toLowerCase()]);
+    }
+  });
+
+  window.addEventListener("beforeunload", (e) => {
+    if (dirty()) e.preventDefault();
+  });
+
+  new ResizeObserver(() => render()).observe(plot);
+
+  return {
+    // keeps the line on show when the song is the same one, refreshed
+    load(id, data) {
+      const same = id === jobId;
+      review = data;
+      root.hidden = false;
+      if (!same) {
+        jobId = id;
+        curve = null;
+        gridDraft = null;
+        fetch(`/api/jobs/${id}/pitch`)
+          .then(r => (r.ok ? r.json() : null))
+          .then(c => { if (jobId === id) { curve = c; render(); } })
+          .catch(() => {});
+      }
+      const lines = visible();
+      if (!lines.length) { root.hidden = true; return; }
+      open(same && lines.some(l => l.index === index) ? index : lines[0].index);
+    },
+    clear() {
+      review = null;
+      jobId = null;
+      curve = null;
+      index = null;
+      view = layout = hist = baseline = preview = gridDraft = null;
+      root.hidden = true;
+    },
+    // playback following the song: never at the cost of unsaved edits
+    showLine(i) {
+      if (review && i !== index && !dirty()) open(i);
+    },
+    isDirty: dirty,
+    setTime(t) {
+      if (!view) return;
+      const inside = t >= view.t0 && t <= view.t1;
+      playhead.hidden = !inside;
+      if (inside) playhead.style.left = `${view.x(t)}px`;
+    },
+  };
+}

src/songtrace/web.py

@@ -0,0 +1,662 @@
+import json
+import math
+import queue
+import re
+import shutil
+import threading
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+import numpy as np
+from fastapi import Body, FastAPI, File, Form, HTTPException, UploadFile
+from fastapi.concurrency import run_in_threadpool
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from . import edits, grid
+from . import rebuild as rebuild_policy
+from .config import Config
+from .lyrics import normalize_lyrics
+from .notes import CONF_MASK
+from .pipeline import (STAGE_ORDER, PipelineError, SongInput, read_warnings,
+                       run_pipeline, song_slug)
+from .ultrastar import get_header, parse_ultrastar
+
+STATIC = Path(__file__).parent / "static"
+STAGE_LINE = re.compile(r"^\[(\w+)\] (?:running|cached, skipping)")
+# the song folder names its own media, exactly as the game reads it
+MEDIA_HEADERS = {"audio": "MP3", "video": "VIDEO", "cover": "COVER"}
+
+
+@dataclass
+class Job:
+    id: str
+    title: str
+    artist: str
+    status: str = "queued"
+    stage: str | None = None
+    log: list[str] = field(default_factory=list)
+    output_dir: str | None = None
+    warnings: list[str] = field(default_factory=list)
+    error: str | None = None
+    inp: SongInput | None = None
+    rebuilt_from: str | None = None
+    force_stage: str | None = None
+    created_at: float = field(default_factory=time.time)
+    started_at: float | None = None
+    finished_at: float | None = None
+
+
+def _safe_filename(name: str | None, default: str) -> str:
+    safe = Path(name).name if name else ""
+    return safe if safe not in ("", ".", "..") else default
+
+
+async def _save_upload(upload: UploadFile, dest: Path) -> None:
+    with dest.open("wb") as f:
+        await run_in_threadpool(shutil.copyfileobj, upload.file, f)
+
+
+async def _store_uploads(cfg: Config, job_id: str, video: UploadFile | None,
+                         cover: UploadFile | None) -> tuple[Path | None, Path | None]:
+    updir = cfg.work_dir / "uploads" / job_id
+    paths = []
+    for upload, default in ((video, "video"), (cover, "cover")):
+        if not (upload and upload.filename):
+            paths.append(None)
+            continue
+        updir.mkdir(parents=True, exist_ok=True)
+        dest = updir / _safe_filename(upload.filename, default)
+        await _save_upload(upload, dest)
+        paths.append(dest)
+    return paths[0], paths[1]
+
+
+def _cleanup_uploads(cfg: Config, job_id: str, video_path: Path | None) -> None:
+    """Drop the video upload a finished job no longer needs.
+
+    Covers are left behind: they are small, and a rebuild inherits cover_path, so
+    removing one would silently strip #COVER from the rebuilt song. A rebuild can
+    also inherit its parent's upload, so the directory is not always uploads/<job_id>.
+    Never raises, so cleaning up cannot fail a job that otherwise succeeded.
+    """
+    uploads = (cfg.work_dir / "uploads").resolve()
+    dirs = {uploads / job_id}
+    if video_path is not None:
+        target = Path(video_path)
+        parent = target.resolve().parent
+        if parent.parent == uploads:
+            try:
+                target.unlink(missing_ok=True)
+            except OSError:
+                pass
+            dirs.add(parent)
+    for d in dirs:
+        try:
+            d.rmdir()
+        except OSError:
+            pass
+
+
+def _discover_jobs(cfg: Config) -> list[Job]:
+    discovered = []
+    if not cfg.work_dir.exists():
+        return discovered
+    for sidecar in cfg.work_dir.glob("*/input.json"):
+        try:
+            data = json.loads(sidecar.read_text())
+            for key in ("video_path", "cover_path"):
+                if data.get(key) is not None:
+                    data[key] = Path(data[key])
+            inp = SongInput(**data)
+            slug = song_slug(inp)
+            out = cfg.output_dir / slug
+            done = out.exists() and any(out.iterdir())
+            mtime = sidecar.stat().st_mtime
+            warnings = read_warnings(sidecar.parent) if done else []
+        except (OSError, ValueError, TypeError):
+            continue
+        discovered.append(Job(
+            id=uuid.uuid4().hex, title=inp.title, artist=inp.artist, inp=inp,
+            status="done" if done else "failed",
+            output_dir=str(out) if done else None,
+            warnings=warnings,
+            error=None if done else "interrupted before completion",
+            created_at=mtime, finished_at=mtime))
+    discovered.sort(key=lambda j: j.created_at)
+    return discovered
+
+
+def create_app(cfg: Config, runner=run_pipeline) -> FastAPI:
+    app = FastAPI()
+    app.mount("/static", StaticFiles(directory=STATIC), name="static")
+    jobs: dict[str, Job] = {}
+    order: list[str] = []
+    lock = threading.Lock()
+    edit_lock = threading.Lock()
+    todo: queue.Queue[str] = queue.Queue()
+
+    for job in _discover_jobs(cfg):
+        jobs[job.id] = job
+        order.append(job.id)
+
+    def _prepare_rebuild(job: Job, log) -> str | None:
+        """Relocate cached work and report the stage this rebuild restarts from."""
+        if not job.rebuilt_from:
+            return job.force_stage
+        with lock:
+            parent = jobs.get(job.rebuilt_from)
+        if parent is None:
+            return job.force_stage
+        planned = rebuild_policy.plan(parent.inp, job.inp)
+        changed = rebuild_policy.changed_fields(parent.inp, job.inp)
+        rebuild_policy.relocate_work(parent.inp, job.inp, cfg)
+        # a stage the operator asked for can only widen what plan() decided,
+        # which is how "redo the packaging" reaches work nothing invalidated
+        force_from = rebuild_policy.earliest(planned, job.force_stage)
+        log(f"[rebuild] restarting from {force_from or 'the first incomplete stage'}"
+            f" ({', '.join(changed) if changed else 'nothing'} changed)")
+        return force_from
+
+    def _drop_superseded_output(job: Job, log) -> None:
+        if not job.rebuilt_from:
+            return
+        with lock:
+            parent = jobs.get(job.rebuilt_from)
+        if parent is None or parent.status != "done":
+            return
+        old = rebuild_policy.superseded_output(parent.output_dir, job.output_dir,
+                                                cfg.output_dir)
+        if old is None:
+            return
+        shutil.rmtree(old, ignore_errors=True)
+        log(f"[rebuild] removed superseded {old.name}")
+
+    def _write_sidecar(job: Job) -> None:
+        work = cfg.work_dir / song_slug(job.inp)
+        work.mkdir(parents=True, exist_ok=True)
+        data = asdict(job.inp)
+        for key in ("video_path", "cover_path"):
+            if data[key] is not None:
+                data[key] = str(data[key])
+        (work / "input.json").write_text(json.dumps(data))
+
+    def worker():
+        while True:
+            job_id = todo.get()
+            with lock:
+                job = jobs[job_id]
+                job.status = "running"
+                job.started_at = time.time()
+
+            def log(msg: str, job=job):
+                with lock:
+                    job.log.append(msg)
+                    if m := STAGE_LINE.match(msg):
+                        job.stage = m[1]
+
+            status, error = "done", None
+            try:
+                force_from = _prepare_rebuild(job, log)
+                _write_sidecar(job)
+                result = runner(job.inp, cfg, log=log, force_from=force_from)
+                with lock:
+                    job.output_dir = str(result.output_dir)
+                    job.warnings = list(result.warnings)
+                _drop_superseded_output(job, log)
+                # uploads survive a failure so the job stays rerunnable; acquire
+                # has already copied the video into the work dir by now.
+                _cleanup_uploads(cfg, job_id, job.inp.video_path)
+            except BaseException as e:
+                status, error = "failed", str(e)
+            # last, and all at once: a client that sees the job finished must
+            # find everything finishing it does already done
+            with lock:
+                job.status, job.error, job.finished_at = status, error, time.time()
+
+    threading.Thread(target=worker, daemon=True).start()
+
+    def _enqueue(job_id: str, inp: SongInput, rebuilt_from: str | None = None,
+                 force_stage: str | None = None) -> dict:
+        job = Job(id=job_id, title=inp.title, artist=inp.artist, inp=inp,
+                  rebuilt_from=rebuilt_from, force_stage=force_stage)
+        with lock:
+            jobs[job_id] = job
+            order.append(job_id)
+        todo.put(job_id)
+        return {"id": job_id}
+
+    def _finished_job(job_id: str) -> Job:
+        with lock:
+            job = jobs.get(job_id)
+            if job is None:
+                raise HTTPException(404)
+            if job.status in ("queued", "running"):
+                raise HTTPException(409, "job is still in progress")
+            return job
+
+    @app.get("/")
+    def index():
+        return FileResponse(STATIC / "index.html")
+
+    @app.post("/api/jobs", status_code=201)
+    async def submit(title: str = Form(...), artist: str = Form(...),
+                      lyrics: str = Form(...), youtube_url: str | None = Form(None),
+                      genre: str | None = Form(None), year: int | None = Form(None),
+                      language: str | None = Form(None), bpm: float | None = Form(None),
+                      video: UploadFile | None = File(None),
+                      cover: UploadFile | None = File(None)):
+        youtube_url, genre, language = (youtube_url or None, genre or None,
+                                        language or None)
+        lyrics = lyrics.replace("\r\n", "\n")
+        has_video = bool(video and video.filename)
+        if bool(youtube_url) == has_video:
+            raise HTTPException(400, "provide exactly one of youtube_url / video")
+        if bpm is not None and (not math.isfinite(bpm) or bpm <= 0):
+            raise HTTPException(400, f"bpm must be a finite value > 0, got {bpm!r}")
+
+        job_id = uuid.uuid4().hex
+        video_path, cover_path = await _store_uploads(cfg, job_id, video, cover)
+
+        inp = SongInput(title=title, artist=artist, lyrics_text=lyrics,
+                         youtube_url=youtube_url, video_path=video_path,
+                         genre=genre, year=year, language=language,
+                         cover_path=cover_path, bpm_override=bpm)
+        return _enqueue(job_id, inp)
+
+    @app.post("/api/jobs/{job_id}/rerun", status_code=201)
+    def rerun(job_id: str):
+        parent = _finished_job(job_id)
+        return _enqueue(uuid.uuid4().hex, parent.inp, rebuilt_from=job_id)
+
+    @app.post("/api/jobs/{job_id}/rebuild-full", status_code=201)
+    def rebuild_full(job_id: str):
+        parent = _finished_job(job_id)
+        return _enqueue(uuid.uuid4().hex, parent.inp, rebuilt_from=job_id,
+                        force_stage=STAGE_ORDER[0])
+
+    def _require_source(parent_inp: SongInput, inp: SongInput,
+                        force_from: str | None) -> None:
+        """Refuse a rebuild that will rerun acquire against an upload we no longer have."""
+        if inp.video_path is None or inp.video_path.exists():
+            return
+        if force_from != "acquire":
+            # acquire is cached under the old slug until the worker renames it
+            for slug in {song_slug(parent_inp), song_slug(inp)}:
+                work = cfg.work_dir / slug
+                if (work / "meta.json").exists() and (work / "audio.wav").exists():
+                    return
+        raise HTTPException(400, "the original video upload is no longer available; "
+                                 "attach the video file again")
+
+    @app.post("/api/jobs/{job_id}/rebuild", status_code=201)
+    async def rebuild(job_id: str, title: str = Form(...), artist: str = Form(...),
+                      lyrics: str = Form(...), youtube_url: str | None = Form(None),
+                      genre: str | None = Form(None), year: int | None = Form(None),
+                      language: str | None = Form(None), bpm: float | None = Form(None),
+                      force_from: str | None = Form(None),
+                      video: UploadFile | None = File(None),
+                      cover: UploadFile | None = File(None)):
+        parent = _finished_job(job_id)
+        force_from = force_from or None
+        if force_from is not None and force_from not in STAGE_ORDER:
+            raise HTTPException(400, f"unknown stage {force_from!r}")
+        # a cleared field arrives as "" from some clients; "" and None must not
+        # look like different inputs to plan()
+        youtube_url, genre, language = (youtube_url or None, genre or None,
+                                        language or None)
+        # a browser submits a textarea with CRLF; without this every rebuild
+        # from the page looks like a lyrics edit and redoes the alignment
+        lyrics = lyrics.replace("\r\n", "\n")
+        has_video = bool(video and video.filename)
+        if youtube_url and has_video:
+            raise HTTPException(400, "provide exactly one of youtube_url / video")
+        if bpm is not None and (not math.isfinite(bpm) or bpm <= 0):
+            raise HTTPException(400, f"bpm must be a finite value > 0, got {bpm!r}")
+
+        new_id = uuid.uuid4().hex
+        video_path, cover_path = await _store_uploads(cfg, new_id, video, cover)
+        if not youtube_url and not has_video:
+            youtube_url, video_path = parent.inp.youtube_url, parent.inp.video_path
+        if cover_path is None:
+            cover_path = parent.inp.cover_path
+
+        inp = SongInput(title=title, artist=artist, lyrics_text=lyrics,
+                        youtube_url=youtube_url, video_path=video_path,
+                        genre=genre, year=year, language=language,
+                        cover_path=cover_path, bpm_override=bpm)
+        _require_source(parent.inp, inp, rebuild_policy.earliest(
+            rebuild_policy.plan(parent.inp, inp), force_from))
+        return _enqueue(new_id, inp, rebuilt_from=job_id, force_stage=force_from)
+
+    def _current_songs() -> list[Job]:
+        """The job that stands for each song now, newest first."""
+        with lock:
+            # a job that was rebuilt is history: its rebuild is the song now,
+            # possibly under another slug
+            rebuilt = {j.rebuilt_from for j in jobs.values()}
+            latest = {song_slug(j.inp): j for j in (jobs[i] for i in order)
+                      if j.id not in rebuilt}
+            position = {job_id: n for n, job_id in enumerate(order)}
+            return sorted(latest.values(), key=lambda j: position[j.id], reverse=True)
+
+    @app.get("/api/rebuild-all")
+    def rebuild_all_candidates():
+        return [{"id": j.id, "title": j.title, "artist": j.artist,
+                 "status": j.status, "rebuilt_from": j.rebuilt_from,
+                 "finished_at": j.finished_at}
+                for j in _current_songs()]
+
+    @app.post("/api/rebuild-all", status_code=201)
+    def rebuild_all(force_from: str = Form(...), ids: list[str] | None = Form(None)):
+        """Rebuild every song, or the ones in `ids`, from `force_from` on, for
+        when songtrace itself improved that stage. Each is an ordinary rebuild
+        with unchanged inputs."""
+        if force_from not in STAGE_ORDER:
+            raise HTTPException(400, f"unknown stage {force_from!r}")
+        songs = _current_songs()
+        queued, skipped = [], []
+        if ids is not None:
+            current = {j.id for j in songs}
+            skipped = [{"id": i, "reason": "no longer the current job for its song"}
+                       for i in ids if i not in current]
+            songs = [j for j in songs if j.id in set(ids)]
+        for job in songs:
+            if job.status in ("queued", "running"):
+                skipped.append({"id": job.id, "reason": "still in progress"})
+                continue
+            try:
+                _require_source(job.inp, job.inp, force_from)
+            except HTTPException as e:
+                skipped.append({"id": job.id, "reason": e.detail})
+                continue
+            queued.append(_enqueue(uuid.uuid4().hex, job.inp, rebuilt_from=job.id,
+                                   force_stage=force_from)["id"])
+        return {"ids": queued, "skipped": skipped}
+
+    @app.get("/api/stages")
+    def list_stages():
+        return {"stages": list(STAGE_ORDER)}
+
+    @app.get("/api/jobs")
+    def list_jobs():
+        with lock:
+            return [{"id": j.id, "title": j.title, "artist": j.artist,
+                      "status": j.status, "stage": j.stage,
+                      "created_at": j.created_at, "started_at": j.started_at,
+                      "finished_at": j.finished_at, "rebuilt_from": j.rebuilt_from}
+                     for j in (jobs[i] for i in reversed(order))]
+
+    @app.get("/api/jobs/{job_id}")
+    def get_job(job_id: str):
+        with lock:
+            job = jobs.get(job_id)
+            if job is None:
+                raise HTTPException(404)
+            return {"id": job.id, "title": job.title, "artist": job.artist,
+                    "status": job.status, "stage": job.stage,
+                    "log": job.log[-100:], "output_dir": job.output_dir,
+                    "warnings": list(job.warnings), "error": job.error,
+                    "created_at": job.created_at, "started_at": job.started_at,
+                    "finished_at": job.finished_at, "rebuilt_from": job.rebuilt_from}
+
+    @app.get("/api/jobs/{job_id}/input")
+    def get_input(job_id: str):
+        with lock:
+            job = jobs.get(job_id)
+            if job is None:
+                raise HTTPException(404)
+            inp = job.inp
+        # keys are the form's field names so the page can prefill by name;
+        # paths are reduced to filenames, which is all the browser can use.
+        return {"title": inp.title, "artist": inp.artist, "lyrics": inp.lyrics_text,
+                "youtube_url": inp.youtube_url, "genre": inp.genre, "year": inp.year,
+                "language": inp.language, "bpm": inp.bpm_override,
+                "video_filename": inp.video_path.name if inp.video_path else None,
+                "cover_filename": inp.cover_path.name if inp.cover_path else None}
+
+    @app.delete("/api/jobs/{job_id}", status_code=204)
+    def delete_job(job_id: str):
+        with lock:
+            job = jobs.get(job_id)
+            if job is None:
+                raise HTTPException(404)
+            if job.status in ("queued", "running"):
+                raise HTTPException(409, "job is still in progress")
+            slug = song_slug(job.inp)
+            if any(other.status in ("queued", "running") and song_slug(other.inp) == slug
+                   for other_id, other in jobs.items() if other_id != job_id):
+                raise HTTPException(409, "another job for this song is in progress")
+            jobs.pop(job_id, None)
+            if job_id in order:
+                order.remove(job_id)
+        shutil.rmtree(cfg.work_dir / slug, ignore_errors=True)
+        shutil.rmtree(cfg.output_dir / slug, ignore_errors=True)
+
+    def _resolve_media(job: Job, header: str) -> Path | None:
+        """The file a song folder's #MP3/#VIDEO/#COVER header points at."""
+        slug = song_slug(job.inp)
+        out = (cfg.output_dir / slug).resolve()
+        txt = out / f"{slug}.txt"
+        if not txt.exists():
+            return None
+        name = get_header(parse_ultrastar(txt.read_text(encoding="utf-8")), header)
+        if not name:
+            return None
+        # a header names a file in the song folder and nothing else
+        path = (out / name).resolve()
+        if path.parent != out or not path.is_file():
+            return None
+        return path
+
+    @app.get("/api/jobs/{job_id}/media/{kind}")
+    def get_media(job_id: str, kind: str):
+        header = MEDIA_HEADERS.get(kind)
+        if header is None:
+            raise HTTPException(404)
+        job = _finished_job(job_id)
+        if job.status != "done":
+            raise HTTPException(404)
+        path = _resolve_media(job, header)
+        if path is None:
+            raise HTTPException(404)
+        return FileResponse(path)
+
+    @app.get("/api/jobs/{job_id}/review")
+    def get_review(job_id: str):
+        job = _finished_job(job_id)
+        if job.status != "done":
+            raise HTTPException(404)
+        work = cfg.work_dir / song_slug(job.inp)
+        notes_file = work / edits.FINAL_FILE
+        if not notes_file.exists():
+            notes_file = work / "notes_sec.json"
+        if not notes_file.exists():
+            raise HTTPException(404)
+        notes_data = json.loads(notes_file.read_text())
+        meta_file = work / "align_meta.json"
+        meta = json.loads(meta_file.read_text()) if meta_file.exists() else {}
+        dropped = set(meta.get("dropped_lines", []))
+        missing_spans = [{"start": s, "end": e}
+                         for s, e in meta.get("missing_spans", [])]
+        align_file = work / "alignment.json"
+        align_rows = json.loads(align_file.read_text()) if align_file.exists() else []
+        words_by_line: dict[int, list] = {}
+        for r in align_rows:
+            words_by_line.setdefault(r["line_index"], []).append(
+                {"text": r["word"], "start": r["start"], "end": r["end"]})
+        ref = normalize_lyrics(job.inp.lyrics_text)
+        by_line: dict[int, list] = {}
+        for n in notes_data["notes"]:
+            by_line.setdefault(n["line_index"], []).append({
+                "start": n["start"], "end": n["start"] + n["duration"],
+                "pitch": n["pitch"], "low_confidence": n["low_confidence"],
+                "text": n["text"], "kind": n.get("kind", ":")})
+        edited = set(notes_data.get("edited_lines", []))
+        lines = [{"index": i, "text": " ".join(words), "dropped": i in dropped,
+                  "edited": i in edited,
+                  "notes": by_line.get(i, []), "words": words_by_line.get(i, [])}
+                 for i, words in enumerate(ref.lines)]
+        stale = [{"text": " ".join(e["words"]), "notes": e["notes"]}
+                 for e in notes_data.get("stale", [])]
+        media = {kind: _resolve_media(job, header) is not None
+                 for kind, header in MEDIA_HEADERS.items()}
+        # each break with the line it comes before, the key a move is saved by
+        moved = set(notes_data.get("moved_breaks", []))
+        starts = sorted((n["start"], n["line_index"]) for n in notes_data["notes"]
+                        if "line_index" in n)
+        breaks = []
+        for t in notes_data.get("breaks", []):
+            after = next((li for start, li in starts if start >= t), None)
+            if after is not None:
+                breaks.append({"line": after, "time": t, "moved": after in moved})
+        return {"lines": lines, "missing_spans": missing_spans, "media": media,
+                "stale": stale, "breaks": breaks, "grid": _chart_grid(work),
+                "grid_edited": bool(notes_data.get("grid")), "auto_bpm": _auto_bpm(work)}
+
+    @app.get("/api/jobs/{job_id}/pitch")
+    def get_pitch(job_id: str):
+        """The detected vocal pitch, to draw behind the notes: UltraStar
+        semitones (0 = C4) every `step` seconds, null where nothing is sung."""
+        job = _finished_job(job_id)
+        path = cfg.work_dir / song_slug(job.inp) / "pitch.npz"
+        if not path.exists():
+            raise HTTPException(404)
+        data = np.load(path)
+        times, f0, conf = data["times"], data["f0"], data["conf"]
+        # every other 10ms frame is still finer than a note can be drawn
+        stride = 2
+        f0, conf = f0[::stride], conf[::stride]
+        voiced = (conf >= CONF_MASK) & (f0 > 0)
+        semis = 9 + 12 * np.log2(np.where(voiced, f0, 440.0) / 440.0)
+        hop = float(times[1] - times[0]) if len(times) > 1 else 0.01
+        return {"start": float(times[0]) if len(times) else 0.0, "step": hop * stride,
+                "pitch": [round(float(v), 2) if ok else None
+                          for v, ok in zip(semis, voiced)]}
+
+    def _chart_grid(work: Path) -> dict | None:
+        """The beat grid the chart was built on, for snapping edits to it."""
+        txt = work / "song.txt"
+        if not txt.exists():
+            return None
+        song = parse_ultrastar(txt.read_text(encoding="utf-8"))
+        bpm, gap = get_header(song, "BPM"), get_header(song, "GAP")
+        if bpm is None or gap is None:
+            return None
+        return {"bpm": float(bpm.replace(",", ".")), "gap_ms": float(gap.replace(",", "."))}
+
+    def _editable(job_id: str) -> Job:
+        job = _finished_job(job_id)
+        slug = song_slug(job.inp)
+        with lock:
+            # a build of this song would overwrite the chart being edited
+            if any(j.status in ("queued", "running") and song_slug(j.inp) == slug
+                   for j in jobs.values()):
+                raise HTTPException(409, "this song is being rebuilt")
+        if job.status != "done":
+            raise HTTPException(409, "only a finished song can be edited")
+        return job
+
+    def _edit(job_id: str, change) -> dict:
+        """Apply `change` to the song's edits, then rewrite its charts."""
+        job = _editable(job_id)
+        work = cfg.work_dir / song_slug(job.inp)
+        lyrics = normalize_lyrics(job.inp.lyrics_text).lines
+        with edit_lock:
+            data = edits.load(work, lyrics)
+            try:
+                change(data, lyrics)
+            except ValueError as e:
+                raise HTTPException(400, str(e))
+            edits.save(work, data)
+            final = edits.finalize(work, lyrics)
+            # the editor's grid, else the pipeline's own tempo with GAP at
+            # the first note, as the grid stage would chart it
+            chosen = final["grid"] or {"bpm": _auto_bpm(work), "gap_ms": None}
+            charts = [work / "song.txt"]
+            if job.output_dir:
+                charts.append(Path(job.output_dir) / f"{song_slug(job.inp)}.txt")
+            for txt in charts:
+                if txt.exists():
+                    grid.rechart(txt, final["notes"], final["breaks"],
+                                 chosen["bpm"], chosen["gap_ms"])
+        with lock:
+            job.warnings = list(final["warnings"])
+        return get_review(job_id)
+
+    def _auto_bpm(work: Path) -> float | None:
+        """The tempo the pipeline chose: recorded by grid, or for a song built
+        before that was, the one its chart already has."""
+        try:
+            return float(json.loads((work / grid.TEMPO_FILE).read_text())["bpm"])
+        except (OSError, ValueError, KeyError):
+            g = _chart_grid(work)
+            return g["bpm"] if g else None
+
+    @app.put("/api/jobs/{job_id}/breaks")
+    def save_breaks(job_id: str, body: dict = Body(...)):
+        """Move line breaks: {line: seconds}, keyed by the line each comes
+        before; null puts one back where the notes alone would place it."""
+        return _edit(job_id, lambda data, lyrics: edits.set_breaks(data, body))
+
+    @app.put("/api/jobs/{job_id}/grid")
+    def save_grid(job_id: str, body: dict = Body(...)):
+        """Set the chart's BPM and GAP, kept through rebuilds like any edit."""
+        job = _editable(job_id)
+        work = cfg.work_dir / song_slug(job.inp)
+        tempo = work / grid.TEMPO_FILE
+        # a song built before grid recorded its tempo: the chart's, taken now
+        # while it is still the pipeline's, is what RESET must return to
+        if not tempo.exists() and (bpm := _auto_bpm(work)) is not None:
+            tempo.write_text(json.dumps({"bpm": bpm}))
+        return _edit(job_id, lambda data, lyrics: edits.set_grid(
+            data, body.get("bpm"), body.get("gap_ms")))
+
+    @app.delete("/api/jobs/{job_id}/grid")
+    def reset_grid(job_id: str):
+        """Go back to the BPM the pipeline chose and GAP at the first note."""
+        def change(data, lyrics):
+            if not edits.clear_grid(data):
+                raise HTTPException(404, "the grid was not set in the editor")
+        return _edit(job_id, change)
+
+    def _line(lyrics, index: int) -> int:
+        if not 0 <= index < len(lyrics):
+            raise HTTPException(404, f"no line {index}")
+        return index
+
+    @app.put("/api/jobs/{job_id}/lines/{index}")
+    def save_line(job_id: str, index: int, body: dict = Body(...)):
+        """Save a line as edited: its full note list, in seconds."""
+        notes = body.get("notes")
+        if not isinstance(notes, list):
+            raise HTTPException(400, "body must be {\"notes\": [...]}")
+        return _edit(job_id, lambda data, lyrics: edits.set_line(
+            data, _line(lyrics, index), notes))
+
+    @app.delete("/api/jobs/{job_id}/lines/{index}")
+    def revert_line(job_id: str, index: int):
+        """Drop a line's edit, so it follows what the pipeline generates."""
+        def change(data, lyrics):
+            if not edits.clear_line(data, _line(lyrics, index)):
+                raise HTTPException(404, f"line {index} has no edit")
+        return _edit(job_id, change)
+
+    @app.delete("/api/jobs/{job_id}/stale/{n}")
+    def discard_stale(job_id: str, n: int):
+        """Throw away an edit whose line's lyrics have since changed."""
+        def change(data, lyrics):
+            if not 0 <= n < len(data["stale"]):
+                raise HTTPException(404, f"no stale edit {n}")
+            data["stale"].pop(n)
+        return _edit(job_id, change)
+
+    return app
+
+
+def serve(cfg: Config) -> int:
+    import uvicorn
+    uvicorn.run(create_app(cfg), host=cfg.bind_host, port=cfg.port)
+    return 0

src/songtrace/whisper_client.py

@@ -0,0 +1,56 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+from .config import Config
+from .languages import LANGUAGES
+
+
+@dataclass
+class TranscriptSegment:
+    start: float
+    end: float
+    text: str
+
+
+def transcribe(cfg: Config, audio_path: Path, language: str | None = None,
+               client: httpx.Client | None = None) -> list[TranscriptSegment]:
+    headers = {}
+    if cfg.whisper_api_key:
+        headers["Authorization"] = f"Bearer {cfg.whisper_api_key}"
+    iso_language = None
+    if language:
+        entry = LANGUAGES.get(language.lower())
+        iso_language = entry.iso if entry else language
+
+    own = client is None
+    client = client or httpx.Client(timeout=600)
+    try:
+        with audio_path.open("rb") as f:
+            if cfg.whisper_api == "asr-webservice":
+                # onerahmet/openai-whisper-asr-webservice: fixed /asr endpoint,
+                # file field is "audio_file", and language/output are query
+                # params rather than form fields - there is no "model" param,
+                # the model is fixed by how that server was started.
+                params = {"output": "json"}
+                if iso_language:
+                    params["language"] = iso_language
+                resp = client.post(
+                    f"{cfg.whisper_url.rstrip('/')}/asr",
+                    headers=headers, params=params,
+                    files={"audio_file": (audio_path.name, f, "audio/wav")})
+            else:
+                data = {"model": cfg.whisper_model, "response_format": "verbose_json"}
+                if iso_language:
+                    data["language"] = iso_language
+                resp = client.post(
+                    f"{cfg.whisper_url.rstrip('/')}/audio/transcriptions",
+                    headers=headers, data=data,
+                    files={"file": (audio_path.name, f, "audio/wav")})
+        resp.raise_for_status()
+        return [TranscriptSegment(s["start"], s["end"], s["text"].strip())
+                for s in resp.json().get("segments", [])]
+    finally:
+        if own:
+            client.close()

src/songtrace/ytdlp.py

@@ -0,0 +1,185 @@
+"""The one place songtrace touches yt-dlp.
+
+YouTube breaks old yt-dlp releases faster than songtrace is released, so
+besides the copy installed with songtrace (the bundled one), newer stable
+releases are fetched from PyPI into a cache dir at runtime and tried first,
+with the bundled copy as the fallback. yt-dlp runs in a subprocess and is
+driven through its command line, its most stable interface, so a cached
+release never mixes with anything songtrace has imported.
+"""
+import importlib.metadata
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+from .config import Config
+from .pipeline import PipelineError
+
+# The extras are what make YouTube work; see pyproject.toml.
+REQUIREMENT = "yt-dlp[default,curl-cffi,deno]"
+CHECK_INTERVAL = 24 * 3600
+_lock = threading.Lock()
+
+
+class YtDlpError(PipelineError):
+    pass
+
+
+def _key(version: str) -> tuple[int, ...]:
+    return tuple(int(p) for p in version.split("."))
+
+
+def cache_dir() -> Path:
+    base = os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache"
+    # Installs hold compiled wheels, so they are only good for one Python.
+    return Path(base) / "songtrace" / f"yt-dlp-py{sys.version_info[0]}{sys.version_info[1]}"
+
+
+@dataclass(frozen=True)
+class YtDlp:
+    version: str
+    path: Path | None = None  # None for the bundled copy
+
+    def _env(self) -> dict[str, str]:
+        env = dict(os.environ)
+        if self.path:
+            env["PYTHONPATH"] = os.pathsep.join(
+                filter(None, [str(self.path), env.get("PYTHONPATH")]))
+            env["PATH"] = os.pathsep.join(
+                [str(self.path / "bin"), env.get("PATH", "")])
+        return env
+
+    def run(self, args: list[str], log) -> None:
+        """Runs yt-dlp with `args`, passing each line it prints to `log`."""
+        proc = subprocess.Popen(
+            [sys.executable, "-P", "-m", "yt_dlp", "--ignore-config", *args],
+            stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+            errors="replace", env=self._env())
+        last = error = ""
+        for line in proc.stdout:
+            last = line.rstrip()
+            log(last)
+            if last.startswith("ERROR:"):
+                error = last
+        if proc.wait() == 0:
+            return
+        if proc.returncode == 2:
+            raise YtDlpError(f"yt-dlp {self.version} rejected songtrace's "
+                             f"options, so it may be incompatible: {last}")
+        raise YtDlpError(error or f"yt-dlp exited with status {proc.returncode}")
+
+
+def bundled() -> YtDlp:
+    return YtDlp(importlib.metadata.version("yt-dlp"))
+
+
+def _latest_release() -> str:
+    r = httpx.get("https://pypi.org/pypi/yt-dlp/json", timeout=15,
+                  follow_redirects=True)
+    r.raise_for_status()
+    return r.json()["info"]["version"]
+
+
+def _pip_install(target: Path, version: str) -> None:
+    proc = subprocess.run(
+        [sys.executable, "-m", "pip", "install", "--quiet", "--no-input",
+         "--disable-pip-version-check", "--target", str(target),
+         f"{REQUIREMENT}=={version}"],
+        capture_output=True, text=True)
+    if proc.returncode:
+        raise YtDlpError(f"pip could not install yt-dlp {version}: "
+                         f"{proc.stderr.strip()[-500:]}")
+
+
+def _install(version: str, log) -> YtDlp:
+    """Installs `version` into the cache unless it is already there.
+
+    The install is checked to run before it is moved into place, so a
+    directory in the cache is always a usable yt-dlp."""
+    dest = cache_dir() / version
+    if dest.is_dir():
+        return YtDlp(version, dest)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    log(f"installing yt-dlp {version}")
+    tmp = Path(tempfile.mkdtemp(dir=dest.parent, prefix=".tmp-"))
+    try:
+        _pip_install(tmp, version)
+        proc = subprocess.run(
+            [sys.executable, "-P", "-m", "yt_dlp", "--version"],
+            capture_output=True, text=True, env=YtDlp(version, tmp)._env())
+        got = proc.stdout.strip()
+        if proc.returncode or _key(got) != _key(version):
+            raise YtDlpError(f"yt-dlp {version} failed its check after install: "
+                             f"{(got or proc.stderr.strip())[-500:]}")
+        try:
+            tmp.rename(dest)
+        except OSError:
+            if not dest.is_dir():
+                raise
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+    return YtDlp(version, dest)
+
+
+def _cached() -> list[YtDlp]:
+    root = cache_dir()
+    if not root.is_dir():
+        return []
+    found = [YtDlp(p.name, p) for p in root.iterdir()
+             if p.is_dir() and re.fullmatch(r"\d+(\.\d+)*", p.name)]
+    return sorted(found, key=lambda y: _key(y.version))
+
+
+def _newest(base: YtDlp, refresh: bool, log) -> YtDlp | None:
+    """The newest cached release newer than `base`, checking PyPI for a newer
+    one first if that has not been done for a day or `refresh` is set."""
+    marker = cache_dir() / ".checked"
+    if (refresh or not marker.exists()
+            or time.time() - marker.stat().st_mtime > CHECK_INTERVAL):
+        # Recorded even on failure, so a broken release is not reinstalled
+        # for every job; a failed download refreshes regardless.
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.touch()
+        try:
+            latest = _latest_release()
+            if _key(latest) > _key(base.version):
+                _install(latest, log)
+        except Exception as e:
+            log(f"could not update yt-dlp: {e}")
+    newer = [y for y in _cached() if _key(y.version) > _key(base.version)]
+    for old in newer[:-1]:
+        shutil.rmtree(old.path, ignore_errors=True)
+    return newer[-1] if newer else None
+
+
+def candidates(cfg: Config, log, refresh: bool = False) -> list[YtDlp]:
+    """The yt-dlp copies to try, in order: the newest release (or the one
+    `cfg.ytdlp_version` pins), then the bundled copy."""
+    base = bundled()
+    want = cfg.ytdlp_version
+    if want == "bundled":
+        return [base]
+    with _lock:
+        if want == "auto":
+            first = _newest(base, refresh, log)
+        elif not re.fullmatch(r"\d+(\.\d+)*", want):
+            raise YtDlpError(f"ytdlp_version must be \"auto\", \"bundled\" or a "
+                             f"release such as \"2026.08.19\", not {want!r}")
+        elif _key(want) == _key(base.version):
+            first = None
+        else:
+            try:
+                first = _install(want, log)
+            except Exception as e:
+                log(f"could not install the pinned yt-dlp {want}: {e}")
+                first = None
+    return [first, base] if first else [base]

tests/fixtures/chart_crlf.txt

@@ -0,0 +1,36 @@
+#TITLE:Placeholder Chart
+#ARTIST:Test Artist
+#LANGUAGE:English
+#YEAR:2000
+#CREATOR:songtrace tests
+#GENRE:Test
+#COVER:Test Artist - Placeholder Chart [CO].jpg
+#MP3:Test Artist - Placeholder Chart.mp3
+#VIDEO:Test Artist - Placeholder Chart.mp4
+#BPM:217,98
+#GAP:4880
+#MEDLEYSTARTBEAT:113
+#MEDLEYENDBEAT:240
+: 0 3 16 ah
+: 5 3 20  ah
+: 11 3 23  la
+: 17 3 16  la
+: 22 28 15  ah
+: 51 2 16  doo
+: 54 31 16 ~
+- 95  
+F 113 3 18 la
+F 117 3 21  la
+F 121 3 21  la
+* 125 3 21  doo
+* 129 12 19 ~
+- 150
+: 155 4 12 Na
+R 160 4 0  na
+G 165 4 0  na
+: 170 6 14  la
+- 190
+: 194 3 16 La
+: 198 3 18  la
+* 202 10 20  ah
+E

tests/fixtures/chart_latin1.txt

@@ -0,0 +1,21 @@
+#TITLE:Café Placeholder
+#ARTIST:Tést Artist
+#LANGUAGE:English
+#GENRE:Test
+#YEAR:2000
+#MP3:Tést Artist - Café Placeholder.mp3
+#CREATOR:songtrace tests
+#BPM:256
+#GAP:49673
+: 0 4 2 Doo
+: 6 4 4  doo
+: 12 8 5  laé
+- 28 30
+: 32 4 0 Na
+: 38 4 -2  na
+* 44 12 -9  ah
+- 64
+F 70 4 3 La
+: 76 6 -5  la
+: 84 10 -9 ~
+E

tests/js/edit-model.test.mjs

@@ -0,0 +1,129 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import * as m from "../../src/songtrace/static/edit-model.js";
+
+// 300 BPM: one UltraStar beat is 0.05s, starting at GAP = 1s
+const GRID = { bpm: 300, gap_ms: 1000 };
+const near = (a, b) => Math.abs(a - b) < 1e-9;
+
+function line() {
+  return m.withIds([
+    { start: 1.52, end: 1.71, pitch: 0, text: "one", kind: ":", low_confidence: false },
+    { start: 1.8, end: 2.0, pitch: 2, text: " two", kind: ":", low_confidence: true },
+  ]);
+}
+
+test("snapping lands on the beat grid from GAP", () => {
+  assert.ok(near(m.snap(1.52, GRID), 1.5));
+  assert.ok(near(m.snap(1.53, GRID), 1.55));
+  assert.ok(near(m.snap(0.97, GRID), 0.95));   // beats before GAP too
+});
+
+test("moving snaps to the grid, then shifts by beats and semitones", () => {
+  const notes = line();
+  const out = m.move(notes, new Set([notes[0].id]), 2, -3, GRID);
+  assert.ok(near(out[0].start, 1.6) && near(out[0].end, 1.8));
+  assert.equal(out[0].pitch, -3);
+  assert.equal(out[1], notes[1]);          // untouched note is the same object
+  assert.equal(notes[0].start, 1.52);      // input left alone
+});
+
+test("moving never goes before the start of the song", () => {
+  const notes = m.withIds([{ start: 0.1, end: 0.2, pitch: 0, text: "x", kind: ":" }]);
+  const out = m.move(notes, new Set([notes[0].id]), -100, 0, GRID);
+  assert.ok(near(out[0].start, 0));
+});
+
+test("resizing moves one edge and keeps at least a beat", () => {
+  const notes = line();
+  const id = notes[0].id;
+  assert.ok(near(m.resize(notes, id, "end", 1.9, GRID)[0].end, 1.9));
+  assert.ok(near(m.resize(notes, id, "end", 1.0, GRID)[0].end, 1.55));
+  const startMoved = m.resize(notes, id, "start", 1.4, GRID)[0];
+  assert.ok(near(startMoved.start, 1.4) && near(startMoved.end, 1.7));
+});
+
+test("stretching changes length by whole beats", () => {
+  const notes = line();
+  const out = m.stretch(notes, new Set([notes[1].id]), 2, GRID);
+  assert.ok(near(out[1].start, 1.8) && near(out[1].end, 2.1));
+  assert.ok(near(m.stretch(notes, new Set([notes[1].id]), -10, GRID)[1].end, 1.85));
+});
+
+test("splitting halves a note on a beat and holds the syllable", () => {
+  const notes = line();
+  const { notes: out, ids } = m.split(notes, notes[1].id, GRID);
+  assert.equal(out.length, 3);
+  assert.ok(near(out[1].end, 1.9) && near(out[2].start, 1.9));
+  assert.deepEqual([out[1].text, out[2].text], [" two", "~"]);
+  assert.equal(ids.length, 2);
+  // one beat cannot be split
+  const short = m.withIds([{ start: 1.0, end: 1.05, pitch: 0, text: "x", kind: ":" }]);
+  assert.equal(m.split(short, short[0].id, GRID).notes, short);
+});
+
+test("merging joins a note with the next, dropping a held ~", () => {
+  const notes = m.withIds([
+    { start: 1.0, end: 1.2, pitch: 0, text: "sev", kind: ":" },
+    { start: 1.2, end: 1.4, pitch: 0, text: "en", kind: ":" },
+    { start: 1.4, end: 1.6, pitch: 0, text: "~", kind: ":" },
+  ]);
+  const once = m.merge(notes, notes[0].id);
+  assert.deepEqual(once.map(n => n.text), ["seven", "~"]);
+  const twice = m.merge(once, once[0].id);
+  assert.deepEqual(twice.map(n => [n.text, n.end]), [["seven", 1.6]]);
+  assert.equal(m.merge(twice, twice[0].id), twice);   // nothing after it
+});
+
+test("inserting adds a two-beat held note on the grid", () => {
+  const { notes, id } = m.insert(line(), 1.76, 4, GRID);
+  const added = notes.find(n => n.id === id);
+  assert.ok(near(added.start, 1.75) && near(added.end, 1.85));
+  assert.deepEqual([added.pitch, added.text, added.kind], [4, "~", ":"]);
+  assert.deepEqual(notes.map(n => n.text), ["one", "~", " two"]);
+});
+
+test("a kind toggles back to normal when every selected note has it", () => {
+  const notes = line();
+  const both = new Set(notes.map(n => n.id));
+  const golden = m.setKind(notes, both, "*");
+  assert.deepEqual(golden.map(n => n.kind), ["*", "*"]);
+  assert.deepEqual(m.setKind(golden, both, "*").map(n => n.kind), [":", ":"]);
+  const mixed = m.setKind(golden, new Set([notes[0].id]), "F");
+  assert.deepEqual(m.setKind(mixed, both, "F").map(n => n.kind), ["F", "F"]);
+});
+
+test("editing text keeps a word-initial space and refuses blank", () => {
+  const notes = line();
+  assert.equal(m.setText(notes, notes[1].id, "too")[1].text, " too");
+  assert.equal(m.setText(notes, notes[0].id, "won")[0].text, "won");
+  assert.equal(m.setText(notes, notes[0].id, " won")[0].text, " won");
+  assert.equal(m.setText(notes, notes[0].id, "   "), notes);
+});
+
+test("saved notes carry duration and kind, not ids", () => {
+  const saved = m.toSaved(line());
+  assert.deepEqual(Object.keys(saved[0]).sort(), ["duration", "kind", "pitch", "start", "text"]);
+  assert.ok(near(saved[0].duration, 0.19));
+});
+
+test("history undoes and redoes, and a new change drops the redo", () => {
+  const h = m.history("a");
+  h.push("b");
+  h.push("c");
+  assert.equal(h.undo(), "b");
+  assert.equal(h.undo(), "a");
+  assert.equal(h.canUndo, false);
+  assert.equal(h.redo(), "b");
+  h.push("d");
+  assert.equal(h.canRedo, false);
+  assert.equal(h.present, "d");
+});
+
+test("a dragged break snaps to a beat but stays between its lines", () => {
+  assert.ok(near(m.placeBreak(1.52, 1.4, 1.8, GRID), 1.5));
+  assert.equal(m.placeBreak(1.0, 1.42, 1.8, GRID), 1.42);   // not into the line before
+  assert.equal(m.placeBreak(2.5, 1.4, 1.78, GRID), 1.78);   // nor into the line after
+  assert.equal(m.placeBreak(1.6, 1.9, 1.8, GRID), 1.9);     // lines overlap: at the end of the first
+});

tests/js/sheet.test.mjs

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { beatLines, isBlackKey, lineSpan, noteName, pitchRange }
+  from "../../src/songtrace/static/sheet.js";
+
+test("note names follow UltraStar's C4 = 0", () => {
+  assert.equal(noteName(0), "C4");
+  assert.equal(noteName(9), "A4");
+  assert.equal(noteName(-1), "B3");
+  assert.equal(noteName(13), "C♯5");
+  assert.equal(noteName(-13), "B2");
+});
+
+test("black keys are the sharps, in any octave", () => {
+  assert.deepEqual([0, 1, 2, 3, 4, 5, 6].map(isBlackKey),
+                   [false, true, false, true, false, false, true]);
+  assert.equal(isBlackKey(-11), true);   // C#3
+  assert.equal(isBlackKey(-12), false);  // C3
+});
+
+test("the pitch range pads the line's notes and keeps a minimum height", () => {
+  assert.deepEqual(pitchRange([0, 5]), { lo: -4, hi: 10 });      // 15 rows
+  assert.deepEqual(pitchRange([0, 20]), { lo: -3, hi: 23 });     // padded only
+  assert.deepEqual(pitchRange([]), { lo: -7, hi: 7 });
+});
+
+test("beat lines sit on the chart's grid with bar weights", () => {
+  // 300 BPM: an UltraStar beat is 60 / (4 * 300) = 0.05s, from GAP 1.0s
+  const lines = beatLines(1.0, 1.85, { bpm: 300, gap_ms: 1000 });
+  assert.equal(lines.length, 18);
+  assert.deepEqual(lines.slice(0, 5).map(b => b.weight), [2, 0, 0, 0, 1]);
+  assert.equal(lines[16].weight, 2);
+  assert.ok(Math.abs(lines[4].t - 1.2) < 1e-9);
+});
+
+test("beats before GAP keep their weights", () => {
+  const lines = beatLines(0.75, 1.0, { bpm: 300, gap_ms: 1000 });
+  assert.deepEqual(lines.map(b => [b.beat, b.weight]),
+                   [[-5, 0], [-4, 1], [-3, 0], [-2, 0], [-1, 0], [0, 2]]);
+});
+
+test("a line spans its notes and words", () => {
+  assert.deepEqual(lineSpan({ notes: [{ start: 2, end: 3 }], words: [{ start: 1.5, end: 2.5 }] }),
+                   { start: 1.5, end: 3 });
+  assert.equal(lineSpan({ notes: [], words: [] }), null);
+});
+
+import { readFileSync } from "node:fs";
+import { SHORTCUTS, comboParts } from "../../src/songtrace/static/sheet.js";
+
+test("shortcut combos split into keys and mouse actions", () => {
+  assert.deepEqual(comboParts("Shift+click / Tab"), [
+    [{ text: "Shift", key: true }, { text: "click", key: false }],
+    [{ text: "Tab", key: true }],
+  ]);
+  assert.deepEqual(comboParts("Page Up"), [[{ text: "Page Up", key: true }]]);
+});
+
+test("every letter key the shortcut list names is one the sheet handles", () => {
+  const source = readFileSync(new URL("../../src/songtrace/static/sheet.js", import.meta.url), "utf8");
+  const handler = source.slice(source.indexOf('plot.addEventListener("keydown"'));
+  const letters = SHORTCUTS.flatMap(([, entries]) => entries)
+    .flatMap(([combo]) => comboParts(combo).flat())
+    .filter(p => p.key && /^[A-Z]$/.test(p.text))
+    .map(p => p.text.toLowerCase());
+  assert.ok(letters.length >= 6);
+  for (const letter of new Set(letters)) {
+    assert.ok(handler.includes(`"${letter}"`) || handler.includes(`${letter}:`),
+              `the list names ${letter.toUpperCase()} but the sheet does not handle it`);
+  }
+});

tests/test_acquire.py

@@ -1,8 +1,8 @@
 import json
 from pathlib import Path
-from karaoke_maker.config import Config
-from karaoke_maker.pipeline import Ctx, SongInput
-from karaoke_maker.stages import acquire
+from songtrace.config import Config
+from songtrace.pipeline import Ctx, SongInput
+from songtrace.stages import acquire
 
 def make_ctx(tmp_path, **kw):
     inp = SongInput(title="T", artist="A", lyrics_text="x", **kw)
@@ -24,7 +24,7 @@ def test_local_video(tmp_path, monkeypatch):
     assert any("audio.wav" in str(a[-1]) for a in calls)
 
 def test_youtube(tmp_path, monkeypatch):
-    def fake_dl(url, dest):
+    def fake_dl(url, dest, cfg, log):
         video = dest / "source_video.webm"
         video.write_bytes(b"v")
         thumb = dest / "source_video.jpg"
@@ -46,7 +46,7 @@ def test_outputs_are_meta_and_audio(tmp_path):
 
 def test_requires_exactly_one_source(tmp_path):
     import pytest
-    from karaoke_maker.pipeline import PipelineError
+    from songtrace.pipeline import PipelineError
     ctx = make_ctx(tmp_path)
     with pytest.raises(PipelineError):
         acquire.acquire_stage().run(ctx)
@@ -73,7 +73,7 @@ def test_classify_no_thumbnail(tmp_path):
 
 def test_classify_no_video_raises(tmp_path):
     import pytest
-    from karaoke_maker.pipeline import PipelineError
+    from songtrace.pipeline import PipelineError
     (tmp_path / "source_video.jpg").write_bytes(b"t")
     with pytest.raises(PipelineError):
         acquire._classify_downloads(tmp_path)
@@ -83,3 +83,120 @@ def test_classify_picks_largest_video_when_multiple(tmp_path):
     (tmp_path / "source_video.mp4").write_bytes(b"much larger contents here")
     video, _ = acquire._classify_downloads(tmp_path)
     assert video.name == "source_video.mp4"
+
+def test_classify_ignores_partials_left_by_a_failed_attempt(tmp_path):
+    (tmp_path / "source_video.webm").write_bytes(b"v")
+    (tmp_path / "source_video.f137.mp4.part").write_bytes(b"a much bigger partial")
+    (tmp_path / "source_video.f251.webm.ytdl").write_bytes(b"resume state")
+    video, _ = acquire._classify_downloads(tmp_path)
+    assert video.name == "source_video.webm"
+
+def test_ydl_args_default_client_adds_no_player_client(tmp_path):
+    cfg = Config(whisper_url="http://x/v1")
+    args = acquire._ydl_args(cfg, tmp_path, "default", "https://yt/x")
+    assert "--extractor-args" not in args
+    assert "--retries" in args and "--fragment-retries" in args
+    assert args[-2:] == ["--", "https://yt/x"]
+
+def test_ydl_args_named_client_pot_provider_and_cookies(tmp_path):
+    cfg = Config(whisper_url="http://x/v1",
+                 ytdlp_pot_provider_url="http://pot:4416",
+                 ytdlp_cookies=tmp_path / "cookies.txt",
+                 ytdlp_impersonate="chrome")
+    args = acquire._ydl_args(cfg, tmp_path, "tv", "https://yt/x")
+    joined = " ".join(args)
+    assert "--extractor-args youtube:player_client=tv" in joined
+    assert ("--extractor-args youtubepot-bgutilhttp:base_url=http://pot:4416"
+            in joined)
+    assert f"--cookies {tmp_path / 'cookies.txt'}" in joined
+    assert "--impersonate chrome" in joined
+
+def test_ydl_args_parse_with_real_yt_dlp(tmp_path):
+    """Every option songtrace passes must exist in the bundled yt-dlp."""
+    import pytest
+    pytest.importorskip("yt_dlp")
+    from yt_dlp import parse_options
+    cfg = Config(whisper_url="http://x/v1", ytdlp_pot_provider_url="http://p:1",
+                 ytdlp_cookies=tmp_path / "c.txt")
+    parse_options(acquire._ydl_args(cfg, tmp_path, "tv", "https://yt/x"))
+
+class FakeYtDlp:
+    def __init__(self, version, behaviour, seen):
+        self.version, self._behaviour, self._seen = version, behaviour, seen
+    def run(self, args, log):
+        client = next((a for a in args if a.startswith("youtube:")), None)
+        self._seen.append((self.version, client))
+        self._behaviour(self.version, client)
+
+def _fake_candidates(monkeypatch, behaviour, versions=("2026.09.01", "2026.08.19"),
+                     refreshed=None):
+    """Stub ytdlp.candidates; `refreshed` is what a refresh turns up."""
+    seen = []
+    def candidates(cfg, log, refresh=False):
+        vs = refreshed if refresh and refreshed else versions
+        return [FakeYtDlp(v, behaviour, seen) for v in vs]
+    monkeypatch.setattr(acquire.ytdlp, "candidates", candidates)
+    return seen
+
+def test_download_falls_through_to_the_next_client(tmp_path, monkeypatch):
+    from songtrace.ytdlp import YtDlpError
+    def behaviour(version, client):
+        if client is None:
+            raise YtDlpError("ERROR: HTTP Error 403: Forbidden")
+        (tmp_path / "source_video.webm").write_bytes(b"v")
+    seen = _fake_candidates(monkeypatch, behaviour)
+    cfg = Config(whisper_url="http://x/v1", ytdlp_clients=["default", "tv"])
+    logged = []
+    video, thumb = acquire.download_youtube("https://yt/x", tmp_path, cfg,
+                                            logged.append)
+    assert video.name == "source_video.webm"
+    assert thumb is None
+    assert seen == [("2026.09.01", None),
+                    ("2026.09.01", "youtube:player_client=tv")]
+    assert any("403" in m for m in logged)
+
+def test_download_falls_back_to_the_bundled_copy(tmp_path, monkeypatch):
+    from songtrace.ytdlp import YtDlpError
+    def behaviour(version, client):
+        if version == "2026.09.01":
+            raise YtDlpError("rejected songtrace's options")
+        (tmp_path / "source_video.webm").write_bytes(b"v")
+    seen = _fake_candidates(monkeypatch, behaviour)
+    cfg = Config(whisper_url="http://x/v1", ytdlp_clients=["default"])
+    acquire.download_youtube("https://yt/x", tmp_path, cfg, lambda m: None)
+    assert [v for v, _ in seen] == ["2026.09.01", "2026.08.19"]
+
+def test_download_retries_with_a_release_found_after_failing(tmp_path, monkeypatch):
+    from songtrace.ytdlp import YtDlpError
+    def behaviour(version, client):
+        if version != "2026.10.01":
+            raise YtDlpError("ERROR: HTTP Error 403: Forbidden")
+        (tmp_path / "source_video.webm").write_bytes(b"v")
+    seen = _fake_candidates(monkeypatch, behaviour,
+                            refreshed=("2026.10.01", "2026.08.19"))
+    cfg = Config(whisper_url="http://x/v1", ytdlp_clients=["default"])
+    acquire.download_youtube("https://yt/x", tmp_path, cfg, lambda m: None)
+    assert [v for v, _ in seen] == ["2026.09.01", "2026.08.19", "2026.10.01"]
+
+def test_download_reports_versions_and_clients_when_all_fail(tmp_path, monkeypatch):
+    import pytest
+    from songtrace.pipeline import PipelineError
+    from songtrace.ytdlp import YtDlpError
+    def behaviour(version, client):
+        raise YtDlpError("ERROR: HTTP Error 403: Forbidden")
+    seen = _fake_candidates(monkeypatch, behaviour)
+    cfg = Config(whisper_url="http://x/v1", ytdlp_clients=["default", "tv"])
+    with pytest.raises(PipelineError) as e:
+        acquire.download_youtube("https://yt/x", tmp_path, cfg, lambda m: None)
+    assert "2026.09.01, 2026.08.19" in str(e.value)
+    assert "default, tv" in str(e.value)
+    assert "403" in str(e.value)
+    assert len(seen) == 4
+
+def test_download_with_no_configured_clients_still_tries_default(tmp_path, monkeypatch):
+    seen = _fake_candidates(
+        monkeypatch,
+        lambda v, c: (tmp_path / "source_video.mp4").write_bytes(b"v"))
+    cfg = Config(whisper_url="http://x/v1", ytdlp_clients=[])
+    acquire.download_youtube("https://yt/x", tmp_path, cfg, lambda m: None)
+    assert seen == [("2026.09.01", None)]

tests/test_align.py

@@ -1,11 +1,23 @@
 import json
 
+import numpy as np
 import pytest
+import soundfile as sf
+
+from songtrace.config import Config
+from songtrace.lyrics import normalize_lyrics
+from songtrace.pipeline import Ctx, PipelineError, SongInput
+from songtrace.stages import align
+from songtrace.whisper_client import TranscriptSegment
+
+REAL_UNTRANSCRIBED_SINGING = align.untranscribed_singing
+
+
+@pytest.fixture(autouse=True)
+def no_untranscribed_singing(monkeypatch):
+    """The tests have no vocals.wav; those about missed singing set their own."""
+    monkeypatch.setattr(align, "untranscribed_singing", lambda vocals, segments: [])
 
-from karaoke_maker.config import Config
-from karaoke_maker.lyrics import normalize_lyrics
-from karaoke_maker.pipeline import Ctx, PipelineError, SongInput
-from karaoke_maker.stages import align
 
 LYRICS = "it's one two three\nfour five six seven eight"
 
@@ -137,3 +149,89 @@ def test_words_split_across_sections(tmp_path, monkeypatch):
     check_invariants(rows, LYRICS)
     assert rows[3]["end"] <= 5.0
     assert rows[4]["start"] >= 29.0
+
+
+def test_align_drops_lines_never_sung(tmp_path, monkeypatch):
+    lyrics = "it's one two three\nfour five six seven eight\nnine ten eleven twelve"
+    transcript = [{"start": 1.0, "end": 4.0,
+                   "text": "it's one two three four five six seven eight"}]
+    rows = run_align(tmp_path, monkeypatch, lyrics, transcript)
+    assert {r["line_index"] for r in rows} == {0, 1}
+    meta = json.loads((tmp_path / "w" / "align_meta.json").read_text())
+    assert meta["dropped_lines"] == [2]
+    assert meta["missing_spans"] == []
+
+
+def test_align_flags_missing_span_for_unmatched_singing(tmp_path, monkeypatch):
+    lyrics = "it's one two three\nfour five six seven eight"
+    transcript = [
+        {"start": 1.0, "end": 4.0, "text": "it's one two three four five six seven eight"},
+        {"start": 20.0, "end": 23.0, "text": "completely unrelated ad lib bridge"},
+    ]
+    run_align(tmp_path, monkeypatch, lyrics, transcript)
+    meta = json.loads((tmp_path / "w" / "align_meta.json").read_text())
+    assert meta["dropped_lines"] == []
+    assert meta["missing_spans"] == [[19.0, 24.0]]
+
+
+def _tone(seconds, sr, level):
+    t = np.arange(int(seconds * sr)) / sr
+    return level * np.sin(2 * np.pi * 220 * t)
+
+
+def test_untranscribed_singing_finds_sung_audio_the_transcript_skips(
+        tmp_path):
+    sr = 16000
+    rng = np.random.default_rng(0)
+    audio = np.concatenate([
+        _tone(2, sr, 0.3),           # 0-2s: sung and transcribed
+        np.zeros(2 * sr),            # 2-4s: silence
+        _tone(5, sr, 0.3),           # 4-9s: sung, never transcribed
+        np.zeros(3 * sr),            # 9-12s: silence
+        _tone(1, sr, 0.3),           # 12-13s: too short to count
+        np.zeros(3 * sr),
+    ]) + 0.001 * rng.standard_normal(16 * sr)   # separation bleed
+    path = tmp_path / "vocals.wav"
+    sf.write(path, audio.astype(np.float32), sr)
+    segments = [TranscriptSegment(0.0, 2.0, "one two")]
+    spans = REAL_UNTRANSCRIBED_SINGING(path, segments)
+    assert len(spans) == 1
+    assert spans[0][0] == pytest.approx(4.0, abs=0.1)
+    assert spans[0][1] == pytest.approx(9.0, abs=0.1)
+
+
+def test_lines_whisper_missed_are_aligned_in_the_untranscribed_singing(
+        tmp_path, monkeypatch):
+    lyrics = "one two three\nfour five six\nseven eight nine"
+    transcript = [{"start": 1.0, "end": 3.0, "text": "one two three"},
+                  {"start": 40.0, "end": 42.0, "text": "seven eight nine"}]
+    monkeypatch.setattr(align, "untranscribed_singing",
+                        lambda vocals, segments: [(20.0, 26.0)])
+    rows = run_align(tmp_path, monkeypatch, lyrics, transcript)
+    check_invariants(rows, lyrics)
+    middle = [r for r in rows if r["line_index"] == 1]
+    assert all(19.0 <= r["start"] and r["end"] <= 27.0 for r in middle)
+    meta = json.loads((tmp_path / "w" / "align_meta.json").read_text())
+    assert meta["dropped_lines"] == []
+
+
+def test_stars_bracket_each_line_and_take_no_words(tmp_path, monkeypatch):
+    lyrics = "one two\n...\nthree four"
+    transcript = [{"start": 0.0, "end": 10.0, "text": "one two three four"}]
+    seen = []
+
+    def spy(vocals_path, start, end, tokens, device):
+        seen.append(tokens)
+        # each star claims a long stretch, so a word given a star's span shows
+        spans = [(start + i, start + i + (5.0 if t == "*" else 0.5), 0.9)
+                 for i, t in enumerate(tokens)]
+        return spans
+
+    monkeypatch.setattr(align, "force_align_section", spy)
+    ctx = make_ctx(tmp_path, lyrics, transcript)
+    align.align_stage().run(ctx)
+    rows = json.loads((ctx.work / "alignment.json").read_text())
+    assert seen == [["*", "one", "two", "*", "three", "four", "*"]]
+    timed = [r for r in rows if r["word"] != "..."]
+    assert all(r["end"] - r["start"] == pytest.approx(0.5) for r in timed)
+    check_invariants(rows, lyrics)

tests/test_audio_io.py

@@ -0,0 +1,26 @@
+import numpy as np
+import soundfile as sf
+
+from songtrace.audio_io import load_wav
+
+
+def test_load_wav_mono(tmp_path):
+    path = tmp_path / "mono.wav"
+    data = np.linspace(-0.5, 0.5, 1600, dtype=np.float32)
+    sf.write(path, data, 16000)
+    waveform, sr = load_wav(path)
+    assert sr == 16000
+    assert waveform.shape == (1, 1600)
+    assert np.allclose(waveform[0].numpy(), data, atol=1e-4)
+
+
+def test_load_wav_stereo(tmp_path):
+    path = tmp_path / "stereo.wav"
+    left = np.linspace(-0.5, 0.5, 800, dtype=np.float32)
+    right = np.linspace(0.5, -0.5, 800, dtype=np.float32)
+    sf.write(path, np.stack([left, right], axis=1), 16000)
+    waveform, sr = load_wav(path)
+    assert sr == 16000
+    assert waveform.shape == (2, 800)
+    assert np.allclose(waveform[0].numpy(), left, atol=1e-4)
+    assert np.allclose(waveform[1].numpy(), right, atol=1e-4)

tests/test_cli.py

@@ -1,5 +1,5 @@
-from karaoke_maker.cli import main
+from songtrace.cli import main
 
 def test_version(capsys):
     assert main(["--version"]) == 0
-    assert "karaoke-maker" in capsys.readouterr().out
+    assert "songtrace" in capsys.readouterr().out

tests/test_cli_make.py

@@ -2,9 +2,9 @@ import os
 
 import pytest
 
-import karaoke_maker.cli as cli
-from karaoke_maker.config import Config
-from karaoke_maker.pipeline import PipelineError, PipelineResult
+import songtrace.cli as cli
+from songtrace.config import Config
+from songtrace.pipeline import PipelineError, PipelineResult
 
 
 def setup_cfg(monkeypatch, tmp_path):

tests/test_config.py

@@ -1,6 +1,6 @@
 import pytest
 from pathlib import Path
-from karaoke_maker.config import Config, load_config
+from songtrace.config import Config, load_config
 
 
 def test_load_minimal(tmp_path):
@@ -24,7 +24,7 @@ def test_paths_and_overrides(tmp_path):
 def test_env_var(tmp_path, monkeypatch):
     cfg_file = tmp_path / "c.toml"
     cfg_file.write_text('whisper_url = "http://env/v1"\n')
-    monkeypatch.setenv("KARAOKE_MAKER_CONFIG", str(cfg_file))
+    monkeypatch.setenv("SONGTRACE_CONFIG", str(cfg_file))
     assert load_config().whisper_url == "http://env/v1"
 
 

tests/test_e2e.py

@@ -4,27 +4,27 @@ import shutil
 import pytest
 
 requires_full = pytest.mark.skipif(
-    not os.environ.get("KARAOKE_E2E"),
-    reason="set KARAOKE_E2E=1 (needs GPU, ffmpeg, whisper server, network)")
+    not os.environ.get("SONGTRACE_E2E"),
+    reason="set SONGTRACE_E2E=1 (needs GPU, ffmpeg, whisper server, network)")
 
 @requires_full
 def test_full_pipeline(tmp_path):
-    from karaoke_maker.config import load_config
-    from karaoke_maker.pipeline import SongInput, run_pipeline
+    from songtrace.config import load_config
+    from songtrace.pipeline import SongInput, run_pipeline
     assert shutil.which("ffmpeg"), "ffmpeg required"
     cfg = load_config()
     cfg.output_dir = tmp_path / "out"
     cfg.work_dir = tmp_path / "work"
     inp = SongInput(
-        title=os.environ["KARAOKE_E2E_TITLE"],
-        artist=os.environ["KARAOKE_E2E_ARTIST"],
-        lyrics_text=open(os.environ["KARAOKE_E2E_LYRICS"]).read(),
-        youtube_url=os.environ.get("KARAOKE_E2E_URL"),
+        title=os.environ["SONGTRACE_E2E_TITLE"],
+        artist=os.environ["SONGTRACE_E2E_ARTIST"],
+        lyrics_text=open(os.environ["SONGTRACE_E2E_LYRICS"]).read(),
+        youtube_url=os.environ.get("SONGTRACE_E2E_URL"),
     )
     result = run_pipeline(inp, cfg)
     txts = list(result.output_dir.glob("*.txt"))
     assert len(txts) == 1
-    from karaoke_maker.ultrastar import get_header, parse_ultrastar
+    from songtrace.ultrastar import get_header, parse_ultrastar
     song = parse_ultrastar(txts[0].read_text(encoding="utf-8"))
     assert get_header(song, "BPM") and get_header(song, "GAP")
     assert len(song.body) > 20

tests/test_edits.py

@@ -0,0 +1,189 @@
+import json
+
+import pytest
+
+from songtrace import edits
+
+LYRICS = [["one", "two"], ["three", "four"], ["five", "six"]]
+
+
+def gen(start, line, pitch=0, dur=0.4, low=False, text="la"):
+    return {"start": start, "duration": dur, "pitch": pitch, "text": text,
+            "low_confidence": low, "line_index": line}
+
+
+def edited(*lines):
+    data = edits._empty(LYRICS)
+    for index, notes in lines:
+        edits.set_line(data, index, notes)
+    return data
+
+
+def note(start, pitch=5, dur=0.4, text="la", kind=":"):
+    return {"start": start, "duration": dur, "pitch": pitch, "text": text, "kind": kind}
+
+
+GENERATED = [gen(1.0, 0), gen(1.5, 0), gen(4.0, 1), gen(4.5, 1), gen(8.0, 2), gen(8.5, 2)]
+BREAKS = [3.0, 6.0]
+
+
+def test_no_edits_leaves_the_generated_song_alone():
+    assert edits.merge(GENERATED, BREAKS, edits._empty(LYRICS)) == (GENERATED, BREAKS)
+
+
+def test_an_edited_line_replaces_its_generated_notes():
+    notes, _ = edits.merge(GENERATED, BREAKS, edited(
+        (1, [note(4.2, pitch=7, kind="*"), note(4.8, pitch=9)])))
+    line1 = [n for n in notes if n["line_index"] == 1]
+    assert [(n["start"], n["pitch"], n["kind"]) for n in line1] == [
+        (4.2, 7, "*"), (4.8, 9, ":")]
+    assert not any(n["low_confidence"] for n in line1)
+    assert [n["line_index"] for n in notes] == [0, 0, 1, 1, 2, 2]
+
+
+def test_neighbours_give_way_to_an_edited_line():
+    # line 1 edited to run from 1.7s to 8.6s, over its neighbours' notes
+    notes, _ = edits.merge(GENERATED, BREAKS, edited(
+        (1, [note(1.7), note(8.2, dur=0.4)])))
+    by_line = {}
+    for n in notes:
+        by_line.setdefault(n["line_index"], []).append(
+            (round(n["start"], 2), round(n["start"] + n["duration"], 2)))
+    assert by_line[0] == [(1.0, 1.4), (1.5, 1.7)]     # cut back to end at 1.7s
+    assert by_line[2] == [(8.6, 8.9)]                 # 8.0 note gone, 8.5 starts at 8.6
+
+
+def test_breaks_beside_an_edited_line_move_and_the_rest_stay():
+    data = edited((2, [note(9.0), note(9.5)]))
+    _, breaks = edits.merge(GENERATED, BREAKS, data)
+    assert breaks[0] == 3.0                           # lines 0-1: generated
+    assert breaks[1] == pytest.approx((4.9 + 9.0) / 2)  # lines 1-2: re-centred
+
+
+def test_an_edit_follows_its_line_when_lines_are_added_above(tmp_path):
+    data = edited((1, [note(4.0)]))
+    edits.save(tmp_path, data)
+    moved = edits.load(tmp_path, [["zero"]] + LYRICS)
+    assert list(moved["lines"]) == ["2"] and moved["lines"]["2"]["line_index"] == 2
+    assert moved["stale"] == []
+    assert json.loads((tmp_path / edits.EDITS_FILE).read_text())["lyrics"][0] == ["zero"]
+
+
+def test_an_edit_whose_words_changed_is_set_aside(tmp_path):
+    edits.save(tmp_path, edited((1, [note(4.0)]), (2, [note(8.0)])))
+    changed = [LYRICS[0], ["three", "more"], LYRICS[2]]
+    data = edits.load(tmp_path, changed)
+    assert list(data["lines"]) == ["2"]
+    assert [s["words"] for s in data["stale"]] == [["three", "four"]]
+
+
+def test_validate_notes_checks_and_orders():
+    assert [n["start"] for n in edits.validate_notes([note(2.0), note(1.0)])] == [1.0, 2.0]
+    for bad in (note(1.0, kind="X"), note(1.0, dur=0), note(-1.0), note(1.0, text=" "),
+                {"start": 1.0}):
+        with pytest.raises(ValueError):
+            edits.validate_notes([bad])
+
+
+def test_saving_no_edits_removes_the_file(tmp_path):
+    edits.save(tmp_path, edited((0, [note(1.0)])))
+    data = edits.load(tmp_path, LYRICS)
+    edits.clear_line(data, 0)
+    edits.save(tmp_path, data)
+    assert not (tmp_path / edits.EDITS_FILE).exists()
+
+
+def _write_generated(work, notes, warnings):
+    (work / "notes_sec.json").write_text(json.dumps(
+        {"notes": notes, "breaks": BREAKS, "warnings": warnings}))
+
+
+def test_finalize_without_edits_passes_warnings_through(tmp_path):
+    _write_generated(tmp_path, GENERATED, ["anything at all"])
+    final = edits.finalize(tmp_path, LYRICS)
+    assert final["warnings"] == ["anything at all"]
+    assert final["edited_lines"] == [] and final["stale"] == []
+    assert json.loads((tmp_path / edits.FINAL_FILE).read_text()) == final
+
+
+def test_finalize_stops_reporting_a_line_the_user_fixed(tmp_path):
+    notes = [gen(1.0, 0), gen(4.0, 1, low=True), gen(8.0, 2)]
+    _write_generated(tmp_path, notes, ["1 low-confidence note near 0:04–0:04",
+                                       "missing lyrics near 0:20–0:25"])
+    edits.save(tmp_path, edited((1, [note(4.0)])))
+    final = edits.finalize(tmp_path, LYRICS)
+    assert final["warnings"] == ["missing lyrics near 0:20–0:25"]
+    assert final["edited_lines"] == [1]
+
+
+def test_finalize_reports_stale_edits(tmp_path):
+    _write_generated(tmp_path, GENERATED, [])
+    edits.save(tmp_path, edited((1, [note(4.0)])))
+    final = edits.finalize(tmp_path, [LYRICS[0], ["other"], LYRICS[2]])
+    assert final["warnings"] == ["1 edited line no longer matches the lyrics; "
+                                 "set aside in the editor"]
+
+
+def test_a_grid_set_in_the_editor_is_checked():
+    data = edits._empty(LYRICS)
+    edits.set_grid(data, "240.5", 1500)
+    assert data["grid"] == {"bpm": 240.5, "gap_ms": 1500.0}
+    for bpm, gap in ((0, 0), (-1, 0), (float("nan"), 0), (3000, 0), (300, -1), ("x", 0)):
+        with pytest.raises(ValueError):
+            edits.set_grid(data, bpm, gap)
+
+
+def test_a_grid_alone_keeps_the_edits_file_and_survives_new_lyrics(tmp_path):
+    data = edits._empty(LYRICS)
+    edits.set_grid(data, 300, 1000)
+    edits.save(tmp_path, data)
+    assert (tmp_path / edits.EDITS_FILE).exists()
+    loaded = edits.load(tmp_path, [["zero"]] + LYRICS)
+    assert loaded["grid"] == {"bpm": 300.0, "gap_ms": 1000.0}
+    assert edits.clear_grid(loaded) and not edits.clear_grid(loaded)
+    edits.save(tmp_path, loaded)
+    assert not (tmp_path / edits.EDITS_FILE).exists()
+
+
+def test_finalize_reports_the_grid(tmp_path):
+    _write_generated(tmp_path, GENERATED, [])
+    assert edits.finalize(tmp_path, LYRICS)["grid"] is None
+    data = edits._empty(LYRICS)
+    edits.set_grid(data, 300, 1000)
+    edits.save(tmp_path, data)
+    assert edits.finalize(tmp_path, LYRICS)["grid"] == {"bpm": 300.0, "gap_ms": 1000.0}
+
+
+def test_moved_breaks_are_checked():
+    data = edits._empty(LYRICS)
+    edits.set_breaks(data, {"1": 3.5, 2: "6.25"})
+    assert data["breaks"] == {"1": 3.5, "2": 6.25}
+    edits.set_breaks(data, {1: None})
+    assert data["breaks"] == {"2": 6.25}
+    for bad in ({0: 1.0}, {3: 1.0}, {"x": 1.0}, {1: -1}, {1: "soon"}, {1: float("inf")}):
+        with pytest.raises(ValueError):
+            edits.set_breaks(data, bad)
+
+
+def test_a_moved_break_stays_put_between_its_lines():
+    data = edits._empty(LYRICS)
+    edits.set_breaks(data, {1: 2.5})
+    notes, breaks = edits.merge(GENERATED, BREAKS, data)
+    assert notes == GENERATED                 # moving a break locks no notes
+    assert breaks == [2.5, 6.0]
+
+
+def test_a_moved_break_never_lands_inside_a_line():
+    data = edits._empty(LYRICS)
+    edits.set_breaks(data, {1: 1.0, 2: 9.0})  # into line 0's notes, past line 2's start
+    _, breaks = edits.merge(GENERATED, BREAKS, data)
+    assert breaks == [pytest.approx(1.9), 8.0]
+
+
+def test_moved_breaks_follow_their_lines_and_keep_the_file(tmp_path):
+    data = edits._empty(LYRICS)
+    edits.set_breaks(data, {1: 3.5, 2: 6.5})
+    edits.save(tmp_path, data)
+    assert (tmp_path / edits.EDITS_FILE).exists()
+    moved = edits.load(tmp_path, [["zero"], LYRICS[0], LYRICS[1], ["other"]])
+    assert moved["breaks"] == {"2": 3.5}      # line 2's words changed: its break goes

tests/test_grid.py

@@ -2,11 +2,11 @@ import json
 
 import numpy as np
 import pytest
-from karaoke_maker.config import Config
-from karaoke_maker.grid import scale_bpm, to_ultrastar
-from karaoke_maker.pipeline import Ctx, PipelineError, SongInput
-from karaoke_maker.stages import all_stages, grid as grid_stage_mod
-from karaoke_maker.ultrastar import (
+from songtrace.config import Config
+from songtrace.grid import scale_bpm, to_ultrastar
+from songtrace.pipeline import Ctx, PipelineError, SongInput
+from songtrace.stages import all_stages, grid as grid_stage_mod
+from songtrace.ultrastar import (
     LineBreak, Note, get_header, parse_ultrastar,
 )
 
@@ -169,7 +169,7 @@ def test_grid_stage_writes_song_txt(tmp_path, monkeypatch):
     monkeypatch.setattr(grid_stage_mod.grid, "detect_bpm", lambda p: 120.0)
     ctx = make_ctx(work, language="English", genre="Pop", year=1999)
     stage = grid_stage_mod.grid_stage()
-    assert stage.outputs(ctx) == [work / "song.txt"]
+    assert stage.outputs(ctx) == [work / "song.txt", work / "notes_final.json"]
     stage.run(ctx)
     song = parse_ultrastar((work / "song.txt").read_text(encoding="utf-8"))
     assert [k for k, _ in song.headers] == [
@@ -222,7 +222,7 @@ def test_grid_stage_honours_zero_bpm_override(tmp_path, monkeypatch):
     monkeypatch.setattr(grid_stage_mod.grid, "detect_bpm", boom)
     captured = {}
 
-    def fake_to_ultrastar(notes, breaks, file_bpm, headers):
+    def fake_to_ultrastar(notes, breaks, file_bpm, headers, gap_ms=None):
         captured["bpm"] = file_bpm
         return to_ultrastar(notes, breaks, 240.0, headers)
 
@@ -257,3 +257,86 @@ def test_grid_stage_reports_no_notes_as_pipeline_error(tmp_path, monkeypatch):
 def test_grid_stage_registered():
     names = [s.name for s in all_stages()]
     assert names[-1] == "package" and names[-2] == "grid"
+
+
+def _regenerate(work, pitch):
+    """What a rebuild leaves: fresh notes for both lines, at `pitch`."""
+    (work / "notes_sec.json").write_text(json.dumps({
+        "notes": [{**note(1.0, 0.5, pitch, "one"), "line_index": 0},
+                  {**note(3.0, 0.5, pitch, "three"), "line_index": 1}],
+        "breaks": [2.0], "warnings": []}))
+
+
+def test_an_edited_line_survives_a_rebuild(tmp_path, monkeypatch):
+    from songtrace import edits
+    work = tmp_path / "w"
+    write_work(work)
+    monkeypatch.setattr(grid_stage_mod.grid, "detect_bpm", lambda p: 120.0)
+    ctx = make_ctx(work)
+    ctx.inp.lyrics_text = "one\nthree"
+    data = edits.load(work, [["one"], ["three"]])
+    edits.set_line(data, 1, [{"start": 3.2, "duration": 0.6, "pitch": 9,
+                              "text": "three", "kind": "*"}])
+    edits.save(work, data)
+    for regenerated_pitch in (0, 4):
+        _regenerate(work, regenerated_pitch)
+        grid_stage_mod.grid_stage().run(ctx)
+        song = parse_ultrastar((work / "song.txt").read_text(encoding="utf-8"))
+        notes = [n for n in song.body if isinstance(n, Note)]
+        assert [(n.kind, n.pitch, n.text) for n in notes] == [
+            (":", regenerated_pitch, "one"), ("*", 9, "three")]
+
+
+def test_rechart_replaces_the_notes_and_keeps_headers_and_tempo(tmp_path):
+    from songtrace.grid import rechart
+    from songtrace.ultrastar import serialize_ultrastar
+    txt = tmp_path / "song.txt"
+    txt.write_text(serialize_ultrastar(to_ultrastar(
+        [note(1.0, 0.5)], [], 300.0,
+        [("TITLE", "Song"), ("VIDEO", "Band - Song.mp4")])), encoding="utf-8")
+    rechart(txt, [{**note(2.0, 0.5, 7, "new"), "kind": "F"}], [])
+    song = parse_ultrastar(txt.read_text(encoding="utf-8"))
+    assert [k for k, _ in song.headers] == ["TITLE", "VIDEO", "BPM", "GAP"]
+    assert get_header(song, "BPM") == "300" and get_header(song, "GAP") == "2000"
+    assert [(n.kind, n.pitch, n.text) for n in song.body] == [("F", 7, "new")]
+
+
+def test_an_explicit_gap_sets_the_grid():
+    # 300 BPM: 0.05s beats; notes at 1.02s and 1.27s against GAP 1.0s
+    song = to_ultrastar([note(1.02, 0.1), note(1.27, 0.1)], [], 300.0, [], gap_ms=1000)
+    assert get_header(song, "GAP") == "1000"
+    assert [n.beat for n in song.body] == [0, 5]
+
+
+def test_a_gap_after_the_first_note_moves_back_by_whole_beats():
+    # GAP 1.13s is after the first note at 1.02s: back 3 beats to 0.98s, so
+    # the grid lines stay where they were set and the note is on beat 1
+    song = to_ultrastar([note(1.02, 0.1)], [], 300.0, [], gap_ms=1130)
+    assert get_header(song, "GAP") == "980"
+    assert song.body[0].beat == 1
+
+
+def test_the_grid_stage_uses_the_editors_grid_and_records_its_own(tmp_path, monkeypatch):
+    from songtrace import edits
+    work = tmp_path / "w"
+    write_work(work)
+    monkeypatch.setattr(grid_stage_mod.grid, "detect_bpm", lambda p: 120.0)
+    ctx = make_ctx(work)
+    data = edits.load(work, [["x"]])
+    edits.set_grid(data, 300.0, 900)
+    edits.save(work, data)
+    grid_stage_mod.grid_stage().run(ctx)
+    song = parse_ultrastar((work / "song.txt").read_text(encoding="utf-8"))
+    assert (get_header(song, "BPM"), get_header(song, "GAP")) == ("300", "900")
+    assert json.loads((work / "tempo.json").read_text()) == {"bpm": 240.0}
+
+
+def test_rechart_can_set_a_new_bpm_and_gap(tmp_path):
+    from songtrace.grid import rechart
+    from songtrace.ultrastar import serialize_ultrastar
+    txt = tmp_path / "song.txt"
+    txt.write_text(serialize_ultrastar(to_ultrastar([note(1.0, 0.5)], [], 240.0, [])),
+                   encoding="utf-8")
+    rechart(txt, [note(1.02, 0.1)], [], 300.0, 1000)
+    song = parse_ultrastar(txt.read_text(encoding="utf-8"))
+    assert (get_header(song, "BPM"), get_header(song, "GAP")) == ("300", "1000")

tests/test_lyrics.py

@@ -1,4 +1,4 @@
-from karaoke_maker.lyrics import normalize_lyrics, alignment_token
+from songtrace.lyrics import normalize_lyrics, alignment_token
 
 RAW = """[Verse 1]
 It's one two three

tests/test_models.py

@@ -0,0 +1,129 @@
+import sys
+import types
+
+import pytest
+
+from songtrace import models
+from songtrace.stages import align, pitch
+
+
+@pytest.fixture
+def isolated_callbacks(monkeypatch):
+    """release() with only the callbacks a test registers."""
+    monkeypatch.setattr(models, "_callbacks", [])
+    return models._callbacks
+
+
+def fake_torch(available=True, initialised=True, emptied=None, reserved=None):
+    """A torch whose allocator reports `reserved` bytes, then 0 once emptied."""
+    state = {"reserved": 4 * 2 ** 20 if reserved is None else reserved}
+
+    def empty_cache():
+        emptied.append(True)
+        state["reserved"] = 0
+
+    mod = types.ModuleType("torch")
+    mod.cuda = types.SimpleNamespace(
+        is_available=lambda: available,
+        is_initialized=lambda: initialised,
+        memory_reserved=lambda: state["reserved"],
+        empty_cache=empty_cache)
+    return mod
+
+
+def test_release_without_torch_or_callbacks_does_nothing(monkeypatch,
+                                                         isolated_callbacks):
+    monkeypatch.delitem(sys.modules, "torch", raising=False)
+    assert models.release() == 0
+
+
+def test_release_runs_every_registered_callback(isolated_callbacks):
+    called = []
+    models.on_release(lambda: called.append("a"))
+    models.on_release(lambda: called.append("b"))
+    models.release()
+    assert called == ["a", "b"]
+
+
+def test_on_release_returns_the_function_so_it_works_as_a_decorator():
+    def drop():
+        pass
+    assert models.on_release(drop) is drop
+    models._callbacks.remove(drop)
+
+
+def test_release_empties_the_allocator_when_cuda_is_in_use(monkeypatch,
+                                                           isolated_callbacks):
+    emptied = []
+    monkeypatch.setitem(sys.modules, "torch", fake_torch(emptied=emptied))
+    assert models.release() == 4 * 2 ** 20
+    assert emptied == [True]
+
+
+def test_release_leaves_the_allocator_alone_without_a_gpu(monkeypatch,
+                                                          isolated_callbacks):
+    emptied = []
+    monkeypatch.setitem(sys.modules, "torch",
+                        fake_torch(available=False, emptied=emptied))
+    assert models.release() == 0
+    assert emptied == []
+
+
+def test_release_does_not_initialise_cuda_just_to_clean_up(monkeypatch,
+                                                           isolated_callbacks):
+    """A run that never touched the GPU must not create a context on the way out."""
+    emptied = []
+    monkeypatch.setitem(sys.modules, "torch",
+                        fake_torch(initialised=False, emptied=emptied))
+    assert models.release() == 0
+    assert emptied == []
+
+
+def test_align_drops_its_cached_model():
+    align._model_cache["cuda"] = object()
+    align.unload_model()
+    assert align._model_cache == {}
+
+
+def test_align_registers_its_unload():
+    assert align.unload_model in models._callbacks
+
+
+def test_pitch_drops_the_model_torchcrepe_cached(monkeypatch):
+    torchcrepe = types.ModuleType("torchcrepe")
+
+    def infer():
+        pass
+
+    infer.model = object()
+    infer.capacity = "full"
+    torchcrepe.infer = infer
+    monkeypatch.setitem(sys.modules, "torchcrepe", torchcrepe)
+    pitch.unload_model()
+    assert not hasattr(infer, "model")
+    assert not hasattr(infer, "capacity")
+
+
+def test_pitch_unload_is_fine_when_torchcrepe_was_never_imported(monkeypatch):
+    monkeypatch.delitem(sys.modules, "torchcrepe", raising=False)
+    pitch.unload_model()
+
+
+def test_pitch_unload_is_fine_when_no_model_was_cached(monkeypatch):
+    torchcrepe = types.ModuleType("torchcrepe")
+    torchcrepe.infer = lambda: None
+    monkeypatch.setitem(sys.modules, "torchcrepe", torchcrepe)
+    pitch.unload_model()
+
+
+def test_pitch_registers_its_unload():
+    assert pitch.unload_model in models._callbacks
+
+
+def test_release_reports_nothing_freed_when_the_allocator_was_already_empty(
+        monkeypatch, isolated_callbacks):
+    emptied = []
+    monkeypatch.setitem(sys.modules, "torch",
+                        fake_torch(emptied=emptied, reserved=0))
+    assert models.release() == 0
+    assert emptied == [True]

tests/test_notes.py

@@ -2,13 +2,13 @@ import json
 
 import numpy as np
 import pytest
-from karaoke_maker.config import Config
-from karaoke_maker.notes import (
-    MIN_NOTE_SEC, TimedNote, build_notes, hz_to_ultrastar, segment_span,
+from songtrace.config import Config
+from songtrace.notes import (
+    MIN_NOTE_SEC, TimedNote, _warnings, build_notes, hz_to_ultrastar, segment_span,
     syllabify,
 )
-from karaoke_maker.pipeline import Ctx, SongInput
-from karaoke_maker.stages import all_stages, notes as notes_stage_mod
+from songtrace.pipeline import Ctx, SongInput
+from songtrace.stages import all_stages, notes as notes_stage_mod
 
 
 def flat_pitch(duration=10.0, hz=261.63):   # C4
@@ -78,7 +78,7 @@ def test_syllabify():
     assert syllabify("reminds", "English") == ["re", "minds"]
     assert syllabify("a", "English") == ["a"]
     assert syllabify("xyzzy", None) == ["xyzzy"]
-    assert syllabify("She's", "English") == ["She's"]
+    assert syllabify("It's", "English") == ["It's"]
 
 
 def test_syllabify_preserves_word_characters():
@@ -96,12 +96,12 @@ def test_syllabify_language_without_pyphen_dict_is_not_mishandled_as_english():
 def test_build_notes_basic_line():
     times, f0, conf = flat_pitch()
     rows = [
-        {"word": "She's", "start": 1.0, "end": 1.5, "score": 0.9, "line_index": 0},
+        {"word": "It's", "start": 1.0, "end": 1.5, "score": 0.9, "line_index": 0},
         {"word": "got", "start": 1.6, "end": 2.0, "score": 0.9, "line_index": 0},
         {"word": "Now", "start": 5.0, "end": 5.5, "score": 0.9, "line_index": 1},
     ]
     notes, breaks, warnings = build_notes(rows, times, f0, conf, "English")
-    assert notes[0].text == "She's"          # line-initial: no leading space
+    assert notes[0].text == "It's"          # line-initial: no leading space
     assert notes[1].text == " got"           # mid-line: leading space
     assert notes[2].text == "Now"            # new line: no leading space
     assert len(breaks) == 1 and 2.0 <= breaks[0] <= 5.0
@@ -127,11 +127,36 @@ def test_build_notes_unvoiced_word_flagged():
     assert warnings[0] == "1 low-confidence note near 0:01–0:01"
 
 
-def test_build_notes_low_score_word_flagged():
+def _scored_rows(scores, dur=0.4):
+    return [{"word": w, "start": 1.0 + i, "end": 1.0 + i + dur, "score": sc,
+             "line_index": 0}
+            for i, (w, sc) in enumerate(zip(["one", "two", "three", "four", "five"], scores))]
+
+
+def test_build_notes_flags_a_word_scoring_far_below_the_rest():
     times, f0, conf = flat_pitch()
-    rows = [{"word": "hey", "start": 1.0, "end": 1.4, "score": 0.1, "line_index": 0}]
-    notes, _, warnings = build_notes(rows, times, f0, conf, "English")
-    assert all(n.low_confidence for n in notes) and len(warnings) == 1
+    notes, _, warnings = build_notes(_scored_rows([0.4, 0.4, 0.05, 0.4, 0.4]),
+                                     times, f0, conf, "English")
+    assert [n.low_confidence for n in notes] == [False, False, True, False, False]
+    assert len(warnings) == 1
+
+
+def test_build_notes_judges_scores_against_the_song_not_a_fixed_cutoff():
+    # sung vocals score low throughout; uniformly low is not a reason to flag
+    times, f0, conf = flat_pitch()
+    notes, _, warnings = build_notes(_scored_rows([0.05] * 5), times, f0, conf, "English")
+    assert not any(n.low_confidence for n in notes) and warnings == []
+
+
+def test_build_notes_flags_words_too_short_or_too_long_to_be_sung():
+    times, f0, conf = flat_pitch()
+    for dur in (0.05, 3.5):
+        rows = _scored_rows([0.4] * 3)
+        rows[1]["end"] = rows[1]["start"] + dur
+        rows[2]["start"], rows[2]["end"] = rows[1]["end"] + 0.1, rows[1]["end"] + 0.5
+        notes, _, _ = build_notes(rows, times, f0, conf, "English")
+        # flat pitch: one note per word
+        assert [n.low_confidence for n in notes] == [False, True, False], dur
 
 
 def test_build_notes_unvoiced_word_inherits_previous_pitch():
@@ -278,7 +303,7 @@ def test_notes_stage_writes_json(tmp_path):
     times, f0, conf = flat_pitch()
     np.savez(work / "pitch.npz", times=times, f0=f0, conf=conf)
     (work / "alignment.json").write_text(json.dumps([
-        {"word": "She's", "start": 1.0, "end": 1.5, "score": 0.9, "line_index": 0},
+        {"word": "It's", "start": 1.0, "end": 1.5, "score": 0.9, "line_index": 0},
         {"word": "gone", "start": 3.0, "end": 3.5, "score": 0.9, "line_index": 1},
     ]))
     ctx = Ctx(inp=SongInput(title="T", artist="A", lyrics_text="x", language="English"),
@@ -287,7 +312,7 @@ def test_notes_stage_writes_json(tmp_path):
     assert stage.outputs(ctx) == [work / "notes_sec.json"]
     stage.run(ctx)
     data = json.loads((work / "notes_sec.json").read_text())
-    assert [n["text"] for n in data["notes"]] == ["She's", "gone"]
+    assert [n["text"] for n in data["notes"]] == ["It's", "gone"]
     assert data["breaks"] == [2.25]
     assert data["warnings"] == []
     assert TimedNote(**data["notes"][0]).pitch == 0
@@ -295,3 +320,52 @@ def test_notes_stage_writes_json(tmp_path):
 
 def test_notes_stage_registered():
     assert "notes" in [s.name for s in all_stages()]
+
+
+def test_build_notes_keeps_matched_words_within_missing_span():
+    # A missing span covers whole Whisper segments, so it can hold matched
+    # lines alongside the unmatched singing; those lines must keep their notes.
+    times, f0, conf = flat_pitch()
+    rows = [
+        {"word": "keep", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 0},
+        {"word": "held", "start": 5.0, "end": 5.4, "score": 0.9, "line_index": 1},
+    ]
+    notes, breaks, warnings = build_notes(rows, times, f0, conf, "English",
+                                          missing_spans=[(4.5, 6.0)])
+    assert [n.text for n in notes] == ["keep", "held"]
+    assert breaks == [(1.4 + 5.0) / 2]
+    assert warnings == ["missing lyrics near 0:04–0:06"]
+
+
+def test_warnings_report_dropped_lines():
+    times, f0, conf = flat_pitch()
+    rows = [{"word": "keep", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 0}]
+    ref_lines = [["keep"], ["the", "outro"]]
+    _, _, warnings = build_notes(rows, times, f0, conf, "English",
+                                 dropped_lines=[1], ref_lines=ref_lines)
+    assert warnings == ['1 line dropped (not sung) near "the outro"']
+
+
+def test_warnings_report_missing_spans():
+    times, f0, conf = flat_pitch()
+    rows = [{"word": "keep", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 0}]
+    _, _, warnings = build_notes(rows, times, f0, conf, "English",
+                                 missing_spans=[(81.0, 89.5)])
+    assert warnings == ["missing lyrics near 1:21–1:29"]
+
+
+def test_notes_carry_line_index():
+    times, f0, conf = flat_pitch()
+    rows = [{"word": "hey", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 3}]
+    notes, _, _ = build_notes(rows, times, f0, conf, "English")
+    assert notes[0].line_index == 3
+
+
+def test_warnings_group_flagged_notes_close_together():
+    def note(start, low):
+        return TimedNote(start, 0.3, 0, "la", low, 0)
+    notes = [note(10.0, True), note(10.5, False), note(11.0, True),   # 0.7s apart
+             note(20.0, True)]                                       # far from both
+    assert _warnings(notes) == [
+        "2 low-confidence notes near 0:10–0:11",
+        "1 low-confidence note near 0:20–0:20"]

tests/test_package.py

@@ -4,12 +4,12 @@ from pathlib import Path
 import pytest
 from PIL import Image
 
-from karaoke_maker.config import Config
-from karaoke_maker.pipeline import (
+from songtrace.config import Config
+from songtrace.pipeline import (
     STAGE_ORDER, Ctx, PipelineError, SongInput, run_pipeline, song_slug,
 )
-from karaoke_maker.stages import all_stages, package
-from karaoke_maker.ultrastar import get_header, parse_ultrastar
+from songtrace.stages import all_stages, package
+from songtrace.ultrastar import get_header, parse_ultrastar
 
 SONG_TXT = ("#TITLE:T\n#ARTIST:A\n#MP3:A - T.mp3\n#COVER:A - T.jpg\n"
             "#VIDEO:A - T.webm\n#BPM:200\n#GAP:0\n: 0 1 0 la\nE\n")
@@ -49,19 +49,37 @@ def make_pipeline_inputs(tmp_path, cover=None):
     return inp, cfg
 
 
-def test_package_copies_compatible_video(tmp_path, monkeypatch):
-    monkeypatch.setattr(package, "ffmpeg", lambda *a: Path(a[-1]).write_bytes(b"m"))
+def test_package_remuxes_compatible_video_without_reencoding(tmp_path, monkeypatch):
+    calls = []
+    monkeypatch.setattr(package, "ffmpeg",
+                        lambda *a: (calls.append(a), Path(a[-1]).write_bytes(b"m")))
     monkeypatch.setattr(package, "ffprobe_codec", lambda p: ("webm", "vp9"))
     ctx = make_ctx(tmp_path, cover=make_cover(tmp_path))
     package.package_stage().run(ctx)
     out = tmp_path / "out" / "A - T"
     assert (out / "A - T.txt").exists()
     assert (out / "A - T.mp3").exists()
-    assert (out / "A - T.webm").read_bytes() == b"v"
+    assert (out / "A - T.webm").exists()
+    video_call = next(c for c in calls if c[-1].endswith("A - T.webm"))
+    assert "-c" in video_call and "copy" in video_call, "the video was re-encoded"
     img = Image.open(out / "A - T.jpg")
     assert img.width == img.height
 
 
+@pytest.mark.parametrize("probe,name", [(("webm", "vp9"), "A - T.webm"),
+                                        (("avi", "mpeg4"), "A - T.mp4")])
+def test_package_strips_the_videos_audio_track(tmp_path, monkeypatch, probe, name):
+    """#MP3 is the song's audio; a video that keeps its own plays as an echo."""
+    calls = []
+    monkeypatch.setattr(package, "ffmpeg",
+                        lambda *a: (calls.append(a), Path(a[-1]).write_bytes(b"m")))
+    monkeypatch.setattr(package, "ffprobe_codec", lambda p: probe)
+    ctx = make_ctx(tmp_path, cover=make_cover(tmp_path))
+    package.package_stage().run(ctx)
+    video_call = next(c for c in calls if c[-1].endswith(name))
+    assert "-an" in video_call
+
+
 def test_package_reencodes_and_rewrites_video_header(tmp_path, monkeypatch):
     monkeypatch.setattr(package, "ffmpeg", lambda *a: Path(a[-1]).write_bytes(b"m"))
     monkeypatch.setattr(package, "ffprobe_codec", lambda p: ("avi", "mpeg4"))

tests/test_pipeline.py

@@ -1,7 +1,7 @@
 import json
 from pathlib import Path
-from karaoke_maker.config import Config
-from karaoke_maker.pipeline import SongInput, Stage, run_pipeline, song_slug
+from songtrace.config import Config
+from songtrace.pipeline import SongInput, Stage, read_warnings, run_pipeline, song_slug
 
 def make_cfg(tmp_path):
     return Config(whisper_url="http://x/v1", output_dir=tmp_path / "out",
@@ -46,3 +46,56 @@ def test_warnings_surfaced(tmp_path):
     st = Stage(name="n", outputs=lambda ctx: [ctx.work / "n.done"], run=run)
     result = run_pipeline(inp, cfg, log=lambda m: None, stages=[st])
     assert result.warnings == ["w1"]
+
+def test_read_warnings_is_empty_without_a_notes_file(tmp_path):
+    assert read_warnings(tmp_path) == []
+
+def test_read_warnings_reads_the_notes_file(tmp_path):
+    (tmp_path / "notes_sec.json").write_text(json.dumps({"warnings": ["w1", "w2"]}))
+    assert read_warnings(tmp_path) == ["w1", "w2"]
+
+def test_gpu_is_released_after_every_stage(tmp_path, monkeypatch):
+    """Not just at the end: a later stage may wait minutes on the Whisper server."""
+    from songtrace import models
+    cfg, inp, calls = make_cfg(tmp_path), make_inp(), []
+    monkeypatch.setattr(models, "release", lambda: calls.append("release"))
+    stages = [fake_stage("s1", calls), fake_stage("s2", calls)]
+    run_pipeline(inp, cfg, log=lambda m: None, stages=stages)
+    assert calls == ["s1", "release", "s2", "release"]
+
+def test_gpu_is_released_when_a_stage_fails(tmp_path, monkeypatch):
+    import pytest
+    from songtrace import models
+    from songtrace.pipeline import PipelineError
+    cfg, inp, calls = make_cfg(tmp_path), make_inp(), []
+    monkeypatch.setattr(models, "release", lambda: calls.append("release"))
+    def boom(ctx):
+        raise PipelineError("boom")
+    stages = [Stage(name="s1", outputs=lambda ctx: [ctx.work / "s1.done"], run=boom)]
+    with pytest.raises(PipelineError):
+        run_pipeline(inp, cfg, log=lambda m: None, stages=stages)
+    assert calls == ["release"]
+
+def test_a_cached_stage_does_not_pay_for_a_release(tmp_path, monkeypatch):
+    from songtrace import models
+    cfg, inp, calls = make_cfg(tmp_path), make_inp(), []
+    stages = [fake_stage("s1", calls)]
+    run_pipeline(inp, cfg, log=lambda m: None, stages=stages)
+    calls.clear()
+    monkeypatch.setattr(models, "release", lambda: calls.append("release"))
+    run_pipeline(inp, cfg, log=lambda m: None, stages=stages)
+    assert calls == []
+
+def test_a_release_that_freed_memory_is_reported_in_the_log(tmp_path, monkeypatch):
+    from songtrace import models
+    cfg, inp, lines = make_cfg(tmp_path), make_inp(), []
+    monkeypatch.setattr(models, "release", lambda: 512 * 2 ** 20)
+    run_pipeline(inp, cfg, log=lines.append, stages=[fake_stage("s1", [])])
+    assert "[s1] released 512 MiB of GPU memory" in lines
+
+def test_a_release_that_freed_nothing_stays_out_of_the_log(tmp_path, monkeypatch):
+    from songtrace import models
+    cfg, inp, lines = make_cfg(tmp_path), make_inp(), []
+    monkeypatch.setattr(models, "release", lambda: 0)
+    run_pipeline(inp, cfg, log=lines.append, stages=[fake_stage("s1", [])])
+    assert not any("released" in line for line in lines)

tests/test_pitch.py

@@ -1,7 +1,7 @@
 import numpy as np
-from karaoke_maker.config import Config
-from karaoke_maker.pipeline import Ctx, SongInput
-from karaoke_maker.stages import pitch
+from songtrace.config import Config
+from songtrace.pipeline import Ctx, SongInput
+from songtrace.stages import pitch
 
 
 def test_pitch_stage_writes_npz(tmp_path, monkeypatch):
@@ -17,3 +17,21 @@ def test_pitch_stage_writes_npz(tmp_path, monkeypatch):
     data = np.load(work / "pitch.npz")
     assert np.allclose(data["f0"], 220.0)
     assert data["times"].shape == data["conf"].shape
+
+
+def test_mute_silence_drops_bleed_but_keeps_quiet_singing():
+    # 60 frames of singing around -30 dB, one quiet sung frame at -50 dB, and
+    # 40 frames of bleed at -60 dB: only the bleed is more than 25 dB below
+    # the song's loud level.
+    loudness = np.array([-30.0] * 60 + [-50.0] + [-60.0] * 40)
+    conf = np.full_like(loudness, 0.8)
+    pitch.mute_silence(conf, loudness)
+    assert (conf[:61] == 0.8).all()
+    assert (conf[61:] == 0.0).all()
+
+
+def test_mute_silence_is_relative_to_the_songs_level():
+    loudness = np.array([-45.0] * 60 + [-75.0] * 40)
+    conf = np.full_like(loudness, 0.8)
+    pitch.mute_silence(conf, loudness)
+    assert (conf[:60] == 0.8).all() and (conf[60:] == 0.0).all()

tests/test_rebuild.py

@@ -3,9 +3,9 @@ from pathlib import Path
 
 import pytest
 
-from karaoke_maker.config import Config
-from karaoke_maker.pipeline import STAGE_ORDER, PipelineError, SongInput
-from karaoke_maker.rebuild import (FIELD_STAGE, changed_fields, plan,
+from songtrace.config import Config
+from songtrace.pipeline import STAGE_ORDER, PipelineError, SongInput
+from songtrace.rebuild import (FIELD_STAGE, changed_fields, earliest, plan,
                                    relocate_work, superseded_output)
 
 
@@ -124,3 +124,14 @@ def test_superseded_output_refuses_a_path_outside_the_output_root(tmp_path):
 def test_superseded_output_refuses_the_output_root_itself(tmp_path):
     root = tmp_path / "out"
     assert superseded_output(str(root), str(root / "A - T"), root) is None
+
+
+def test_earliest_picks_the_earlier_stage():
+    assert earliest("package", "separate") == "separate"
+    assert earliest("separate", "package") == "separate"
+
+
+def test_earliest_ignores_unset_stages():
+    assert earliest(None, "grid") == "grid"
+    assert earliest("grid", None) == "grid"
+    assert earliest(None, None) is None

tests/test_separate.py

@@ -1,9 +1,9 @@
 import numpy as np
 import soundfile as sf
 import torch
-from karaoke_maker.config import Config
-from karaoke_maker.pipeline import Ctx, SongInput
-from karaoke_maker.stages import separate
+from songtrace.config import Config
+from songtrace.pipeline import Ctx, SongInput
+from songtrace.stages import separate
 
 
 def test_separate_writes_stems(tmp_path, monkeypatch):

tests/test_static_js.py

@@ -0,0 +1,15 @@
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+
+def test_static_js_unit_tests():
+    """The page's own logic, run under Node's test runner."""
+    node = shutil.which("node")
+    if node is None:
+        pytest.skip("node is not installed")
+    tests = sorted(str(p) for p in (Path(__file__).parent / "js").glob("*.test.mjs"))
+    proc = subprocess.run([node, "--test", *tests], capture_output=True, text=True)
+    assert proc.returncode == 0, proc.stdout + proc.stderr

tests/test_transcribe.py

@@ -1,6 +1,7 @@
-from karaoke_maker.lyrics import normalize_lyrics
-from karaoke_maker.whisper_client import TranscriptSegment
-from karaoke_maker.stages.transcribe import lyrics_similarity, vocal_sections
+from songtrace.lyrics import normalize_lyrics
+from songtrace.whisper_client import TranscriptSegment
+from songtrace.stages.transcribe import (classify_lyrics_match, lyrics_similarity,
+                                         recovered_spans, vocal_sections)
 
 def seg(s, e, t=""):
     return TranscriptSegment(start=s, end=e, text=t)
@@ -26,3 +27,69 @@ def test_similarity_low_for_wrong_lyrics():
     ref = normalize_lyrics("completely different words here entirely")
     segs = [seg(0, 2, "it's one two three four five six seven eight")]
     assert lyrics_similarity(segs, ref) < 0.4
+
+def test_classify_lyrics_match_flags_extra_reference_line():
+    ref = normalize_lyrics("it's one two three\nfour five six seven eight\nnine ten eleven")
+    segs = [seg(1, 4, "it's one two three four five six seven eight")]
+    dropped, missing = classify_lyrics_match(segs, ref)
+    assert dropped == [2]
+    assert missing == []
+
+def test_classify_lyrics_match_flags_unmatched_singing():
+    ref = normalize_lyrics("it's one two three\nfour five six seven eight")
+    segs = [seg(1, 4, "it's one two three four five six seven eight"),
+            seg(20, 23, "completely unrelated ad lib bridge")]
+    dropped, missing = classify_lyrics_match(segs, ref)
+    assert dropped == []
+    assert missing == [(19.0, 24.0)]
+
+def test_classify_lyrics_match_keeps_partially_matched_lines():
+    ref = normalize_lyrics("it's one two three\nfour five six seven eight")
+    # line 1 heard with one word garbled ("five" -> "fife"): still a replace/equal
+    # match, so the line stays matched rather than dropped
+    segs = [seg(1, 4, "it's one two three four fife six seven eight")]
+    dropped, _ = classify_lyrics_match(segs, ref)
+    assert dropped == []
+
+def test_classify_lyrics_match_scopes_missing_span_to_adlib_not_whole_section():
+    # matched line and an unmatched ad-lib close enough together that
+    # vocal_sections would merge them into one section; missing_spans must
+    # stay tight around the ad-lib so the review marks the right place.
+    ref = normalize_lyrics("it's one two three\nfour five six seven eight")
+    segs = [seg(1, 4, "it's one two three four five six seven eight"),
+            seg(6, 8, "completely unrelated ad lib")]
+    sections = vocal_sections(segs)
+    assert sections == [(0.0, 9.0)]      # confirms the two segments do merge
+    dropped, missing = classify_lyrics_match(segs, ref)
+    assert dropped == []
+    assert missing == [(5.0, 9.0)]
+    for a, b in missing:
+        assert not (a <= 1.0 < b)        # matched line's start (1.0) untouched
+
+
+THREE_LINES = "one two three\nfour five six\nseven eight nine"
+
+
+def test_lines_whisper_missed_are_kept_when_singing_went_untranscribed():
+    ref = normalize_lyrics(THREE_LINES)
+    segs = [seg(0, 2, "one two three"), seg(20, 22, "seven eight nine")]
+    assert classify_lyrics_match(segs, ref)[0] == [1]
+    dropped, _ = classify_lyrics_match(segs, ref, unheard=[(8.0, 14.0)])
+    assert dropped == []
+
+
+def test_untranscribed_singing_elsewhere_does_not_keep_a_line():
+    ref = normalize_lyrics(THREE_LINES)
+    segs = [seg(0, 2, "one two three"), seg(20, 22, "seven eight nine")]
+    dropped, _ = classify_lyrics_match(segs, ref, unheard=[(30.0, 35.0)])
+    assert dropped == [1]
+
+
+def test_recovered_spans_are_the_singing_between_heard_neighbours():
+    ref = normalize_lyrics(THREE_LINES)
+    segs = [seg(10, 12, "four five six"), seg(20, 22, "seven eight nine")]
+    unheard = [(3.0, 9.0), (14.0, 18.0), (30.0, 35.0)]
+    # line 0 comes before anything heard, so only the singing before line 1
+    # can stand in for it; the other spans have no missing line around them
+    assert recovered_spans(segs, ref, unheard) == [(3.0, 9.0)]
+    assert classify_lyrics_match(segs, ref, unheard=unheard)[0] == []

tests/test_ultrastar.py

@@ -1,5 +1,5 @@
 from pathlib import Path
-from karaoke_maker.ultrastar import (
+from songtrace.ultrastar import (
     Note, LineBreak, parse_ultrastar, serialize_ultrastar,
     get_header, format_bpm, parse_bpm,
 )
@@ -10,8 +10,8 @@ def load(name):
     return (FIXTURES / name).read_text(encoding="utf-8", errors="replace")
 
 def test_parse_headers_and_notes():
-    song = parse_ultrastar(load("sanctuary.txt"))
-    assert get_header(song, "artist") == "Utada Hikaru"
+    song = parse_ultrastar(load("chart_crlf.txt"))
+    assert get_header(song, "artist") == "Test Artist"
     assert parse_bpm(get_header(song, "BPM")) == 217.98
     first = song.body[0]
     assert first == Note(kind=":", beat=0, length=3, pitch=16, text="ah")
@@ -19,16 +19,16 @@ def test_parse_headers_and_notes():
     assert any(n.kind == "F" for n in song.body if isinstance(n, Note))
 
 def test_note_text_keeps_leading_space():
-    song = parse_ultrastar(load("sanctuary.txt"))
+    song = parse_ultrastar(load("chart_crlf.txt"))
     notes = [n for n in song.body if isinstance(n, Note)]
     assert notes[1].text == " ah"
 
 def test_negative_pitch():
-    song = parse_ultrastar(load("sweet_child.txt"))
+    song = parse_ultrastar(load("chart_latin1.txt"))
     assert any(n.pitch == -9 for n in song.body if isinstance(n, Note))
 
 def test_round_trip():
-    for name in ("sweet_child.txt", "sanctuary.txt"):
+    for name in ("chart_latin1.txt", "chart_crlf.txt"):
         song = parse_ultrastar(load(name))
         again = parse_ultrastar(serialize_ultrastar(song))
         assert again == song

tests/test_whisper.py

@@ -1,7 +1,7 @@
 import httpx
 from pathlib import Path
-from karaoke_maker.config import Config
-from karaoke_maker.whisper_client import TranscriptSegment, transcribe
+from songtrace.config import Config
+from songtrace.whisper_client import TranscriptSegment, transcribe
 
 def test_transcribe_parses_segments(tmp_path):
     audio = tmp_path / "v.wav"
@@ -36,3 +36,25 @@ def test_transcribe_maps_language_to_iso_code(tmp_path):
     transcribe(cfg, audio, language="Japanese", client=client)
     assert 'name="language"' in seen["body"]
     assert "\r\n\r\nja\r\n" in seen["body"]
+
+
+def test_transcribe_asr_webservice_hits_fixed_asr_endpoint(tmp_path):
+    audio = tmp_path / "v.wav"
+    audio.write_bytes(b"RIFF")
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["url"] = str(request.url)
+        seen["body"] = request.read().decode("utf-8", errors="replace")
+        return httpx.Response(200, json={
+            "text": "hello world",
+            "segments": [{"start": 0.5, "end": 2.0, "text": " hello world"}],
+        })
+
+    client = httpx.Client(transport=httpx.MockTransport(handler))
+    cfg = Config(whisper_url="http://w:9000", whisper_api="asr-webservice")
+    segs = transcribe(cfg, audio, language="Japanese", client=client)
+    assert segs == [TranscriptSegment(start=0.5, end=2.0, text="hello world")]
+    assert seen["url"] == "http://w:9000/asr?output=json&language=ja"
+    assert 'name="audio_file"' in seen["body"]
+    assert 'name="model"' not in seen["body"]

tests/test_ytdlp.py

@@ -0,0 +1,139 @@
+import os
+import time
+
+import pytest
+
+from songtrace import ytdlp
+from songtrace.config import Config
+from songtrace.ytdlp import YtDlp, YtDlpError
+
+
+def fake_package(path, version="2026.09.01", body=""):
+    """A stand-in yt_dlp that answers --version and otherwise runs `body`."""
+    pkg = path / "yt_dlp"
+    pkg.mkdir(parents=True)
+    (pkg / "__init__.py").touch()
+    (pkg / "__main__.py").write_text(
+        "import sys\n"
+        f"if '--version' in sys.argv: print({version!r}); sys.exit()\n"
+        + body)
+    return path
+
+
+@pytest.fixture
+def cache(tmp_path, monkeypatch):
+    monkeypatch.setenv("XDG_CACHE_HOME", str(tmp_path / "cache"))
+    monkeypatch.setattr(ytdlp, "bundled", lambda: YtDlp("2026.8.19"))
+    return ytdlp.cache_dir()
+
+
+@pytest.fixture
+def pypi(monkeypatch):
+    """Stubs PyPI and pip: `latest` is the newest release, `installs` logs pip."""
+    state = {"latest": "2026.9.1", "installs": []}
+    monkeypatch.setattr(ytdlp, "_latest_release", lambda: state["latest"])
+    def pip_install(target, version):
+        state["installs"].append(version)
+        fake_package(target, version)
+    monkeypatch.setattr(ytdlp, "_pip_install", pip_install)
+    return state
+
+
+def cfg(version="auto"):
+    return Config(whisper_url="http://x/v1", ytdlp_version=version)
+
+
+def test_run_uses_the_install_on_its_path_and_logs_its_output(tmp_path):
+    path = fake_package(tmp_path, body="print('[youtube] hello', sys.argv[1:])\n")
+    logged = []
+    YtDlp("2026.09.01", path).run(["--", "https://yt/x"], logged.append)
+    assert logged == ["[youtube] hello ['--ignore-config', '--', 'https://yt/x']"]
+
+
+def test_run_raises_the_error_line(tmp_path):
+    path = fake_package(tmp_path, body=(
+        "print('ERROR: HTTP Error 403: Forbidden', file=sys.stderr)\n"
+        "print('trailing noise')\nsys.exit(1)\n"))
+    with pytest.raises(YtDlpError, match="^ERROR: HTTP Error 403"):
+        YtDlp("2026.09.01", path).run([], lambda m: None)
+
+
+def test_run_flags_a_usage_error_as_incompatible(tmp_path):
+    path = fake_package(tmp_path, body=(
+        "print('error: no such option: --retries', file=sys.stderr)\n"
+        "sys.exit(2)\n"))
+    with pytest.raises(YtDlpError, match="2026.09.01 rejected.*--retries"):
+        YtDlp("2026.09.01", path).run([], lambda m: None)
+
+
+def test_auto_installs_a_newer_release_and_tries_it_first(cache, pypi):
+    found = ytdlp.candidates(cfg(), lambda m: None)
+    assert [y.version for y in found] == ["2026.9.1", "2026.8.19"]
+    assert found[0].path == cache / "2026.9.1"
+    assert not [p for p in cache.iterdir() if p.name.startswith(".tmp-")]
+
+
+def test_auto_checks_pypi_once_a_day(cache, pypi):
+    ytdlp.candidates(cfg(), lambda m: None)
+    pypi["latest"] = "2026.10.1"
+    found = ytdlp.candidates(cfg(), lambda m: None)
+    assert found[0].version == "2026.9.1"
+    found = ytdlp.candidates(cfg(), lambda m: None, refresh=True)
+    assert found[0].version == "2026.10.1"
+    assert not (cache / "2026.9.1").exists()
+    old = time.time() - ytdlp.CHECK_INTERVAL - 1
+    os.utime(cache / ".checked", (old, old))
+    pypi["latest"] = "2026.11.1"
+    assert ytdlp.candidates(cfg(), lambda m: None)[0].version == "2026.11.1"
+
+
+def test_auto_uses_only_bundled_when_it_is_newest(cache, pypi):
+    pypi["latest"] = "2026.8.19"
+    assert [y.version for y in ytdlp.candidates(cfg(), lambda m: None)] == [
+        "2026.8.19"]
+    assert pypi["installs"] == []
+
+
+def test_auto_survives_pypi_being_unreachable(cache, pypi, monkeypatch):
+    ytdlp.candidates(cfg(), lambda m: None)
+    def down():
+        raise OSError("network unreachable")
+    monkeypatch.setattr(ytdlp, "_latest_release", down)
+    logged = []
+    found = ytdlp.candidates(cfg(), logged.append, refresh=True)
+    assert [y.version for y in found] == ["2026.9.1", "2026.8.19"]
+    assert any("network unreachable" in m for m in logged)
+
+
+def test_an_install_that_fails_its_check_is_discarded(cache, pypi, monkeypatch):
+    monkeypatch.setattr(ytdlp, "_pip_install",
+                        lambda target, v: fake_package(target, "2026.1.1"))
+    logged = []
+    assert [y.version for y in ytdlp.candidates(cfg(), logged.append)] == [
+        "2026.8.19"]
+    assert any("failed its check" in m for m in logged)
+    assert list(cache.iterdir()) == [cache / ".checked"]
+
+
+def test_bundled_never_touches_pypi(cache, pypi):
+    pypi["latest"] = None
+    assert [y.version for y in ytdlp.candidates(cfg("bundled"), print)] == [
+        "2026.8.19"]
+    assert not cache.exists()
+
+
+def test_pin_installs_that_release_even_if_older(cache, pypi):
+    found = ytdlp.candidates(cfg("2026.07.01"), lambda m: None)
+    assert [y.version for y in found] == ["2026.07.01", "2026.8.19"]
+    assert pypi["installs"] == ["2026.07.01"]
+
+
+def test_pin_matching_bundled_installs_nothing(cache, pypi):
+    found = ytdlp.candidates(cfg("2026.08.19"), lambda m: None)
+    assert [y.version for y in found] == ["2026.8.19"]
+    assert pypi["installs"] == []
+
+
+def test_pin_must_be_a_release_number(cache, pypi):
+    with pytest.raises(YtDlpError, match="ytdlp_version"):
+        ytdlp.candidates(cfg("latest; rm -rf /"), lambda m: None)