Merge remote-tracking branch 'origin/main' into unheard-lines

Reviewed-on: #26
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

@@ -0,0 +1,19 @@
+# torch pip wheels bundle their own CUDA runtime libs; only the host NVIDIA
+# driver is needed (exposed via the nvidia container runtime), so a plain
+# Python base is sufficient — no CUDA base image required.
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY pyproject.toml ./
+COPY src ./src
+RUN pip install --no-cache-dir .
+
+ENV SONGTRACE_CONFIG=/config/config.toml \
+    TORCH_HOME=/data/models \
+    XDG_CACHE_HOME=/data/models/cache
+
+EXPOSE 8000
+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

@@ -0,0 +1,244 @@
+# 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. 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 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
+6. **notes** — turn word timings + pitch into UltraStar notes
+7. **grid** — quantise notes to a beat grid
+8. **package** — write the final song folder (`.txt` + `.mp3` + video + cover)
+
+The shipped `.mp3` is the full original mix (vocals included) — the
+separated stems are used for analysis only and are not included in the
+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](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.
+
+## Configuration
+
+Config is TOML. Resolution order:
+
+1. `--config <path>` passed explicitly on the command line
+2. the `SONGTRACE_CONFIG` environment variable
+3. `~/.config/songtrace/config.toml`
+
+Copy the example and fill in your Whisper server:
+
+```sh
+cp config.example.toml config.toml
+$EDITOR config.toml   # set whisper_url at minimum
+```
+
+See `config.example.toml` for every available field (`whisper_url`,
+`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
+
+```sh
+cp config.example.toml config.toml
+$EDITOR config.toml
+docker compose up -d
+```
+
+The web UI is then at `http://localhost:8000`. Downloaded model weights
+(Demucs, wav2vec2, ...) are cached under `./data` on the host so they survive
+container recreation.
+
+Run the CLI inside the container instead of the web UI:
+
+```sh
+docker compose run --rm songtrace songtrace make \
+  --title "Song Title" --artist "Artist Name" \
+  --lyrics /data/lyrics.txt --youtube https://youtu.be/...
+```
+
+GPU passthrough requires the [NVIDIA Container
+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 .
+songtrace make --help
+```
+
+```
+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 `songtrace serve [--config CONFIG]`.
+
+## Re-running a stage
+
+Each stage caches its output under `work_dir`. If a later stage needs
+another pass (e.g. you want to retry alignment with different lyrics, or
+pitch tracking looks off), re-run with `--force-from <stage>` to redo that
+stage and everything after it, reusing the cached output of everything
+before it:
+
+```sh
+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

@@ -0,0 +1,23 @@
+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"
+# demucs_model = "htdemucs_ft"
+# crepe_model = "full"
+# 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

@@ -0,0 +1,15 @@
+services:
+  songtrace:
+    build: .
+    ports:
+      - "8000:8000"
+    volumes:
+      - ./config.toml:/config/config.toml:ro
+      - ./data:/data
+    deploy:
+      resources:
+        reservations:
+          devices:
+            - driver: nvidia
+              count: 1
+              capabilities: [gpu]

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"]
@@ -34,5 +40,8 @@ build-backend = "setuptools.build_meta"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+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/cli.py

@@ -1,16 +0,0 @@
-import argparse
-from importlib.metadata import version
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="karaoke-maker")
-    parser.add_argument("--version", action="store_true")
-    parser.add_subparsers(dest="command")
-    return parser
-
-def main(argv: list[str] | None = None) -> int:
-    args = build_parser().parse_args(argv)
-    if args.version:
-        print(f"karaoke-maker {version('karaoke-maker')}")
-        return 0
-    build_parser().print_help()
-    return 0

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

@@ -0,0 +1,83 @@
+import argparse
+import math
+import sys
+from importlib.metadata import version
+from pathlib import Path
+
+from .config import load_config
+from .pipeline import STAGE_ORDER, PipelineError, SongInput, run_pipeline
+
+
+def _positive_float(value: str) -> float:
+    bpm = float(value)
+    if not math.isfinite(bpm) or bpm <= 0:
+        raise argparse.ArgumentTypeError(f"--bpm must be a finite value > 0, got {value!r}")
+    return bpm
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="songtrace")
+    parser.add_argument("--version", action="store_true")
+    sub = parser.add_subparsers(dest="command")
+
+    make = sub.add_parser("make", help="build a karaoke song folder")
+    make.add_argument("--title", required=True)
+    make.add_argument("--artist", required=True)
+    make.add_argument("--lyrics", required=True, type=Path)
+    make.add_argument("--youtube")
+    make.add_argument("--video", type=Path)
+    make.add_argument("--genre")
+    make.add_argument("--year", type=int)
+    make.add_argument("--language")
+    make.add_argument("--cover", type=Path)
+    make.add_argument("--bpm", type=_positive_float)
+    make.add_argument("--force-from", choices=STAGE_ORDER)
+    make.add_argument("--config", type=Path)
+
+    serve = sub.add_parser("serve", help="run the web UI")
+    serve.add_argument("--config", type=Path)
+    return parser
+
+
+def _cmd_make(args) -> int:
+    if bool(args.youtube) == bool(args.video):
+        print("error: provide exactly one of --youtube / --video", file=sys.stderr)
+        return 2
+    try:
+        lyrics_text = args.lyrics.read_text(encoding="utf-8")
+    except OSError as e:
+        print(f"error: could not read --lyrics file: {e}", file=sys.stderr)
+        return 2
+    except UnicodeDecodeError as e:
+        print(f"error: --lyrics file is not valid UTF-8 text: {e}", file=sys.stderr)
+        return 2
+    cfg = load_config(args.config)
+    inp = SongInput(
+        title=args.title, artist=args.artist,
+        lyrics_text=lyrics_text,
+        youtube_url=args.youtube, video_path=args.video,
+        genre=args.genre, year=args.year, language=args.language,
+        cover_path=args.cover, bpm_override=args.bpm)
+    try:
+        result = run_pipeline(inp, cfg, force_from=args.force_from)
+    except PipelineError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+    print(f"done: {result.output_dir}")
+    for w in result.warnings:
+        print(f"  review: {w}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.version:
+        print(f"songtrace {version('songtrace')}")
+        return 0
+    if args.command == "make":
+        return _cmd_make(args)
+    if args.command == "serve":
+        from .web import serve
+        return serve(load_config(args.config))
+    build_parser().print_help()
+    return 0

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/grid.py

@@ -0,0 +1,58 @@
+import math
+from pathlib import Path
+
+import numpy as np
+
+from .ultrastar import LineBreak, Note, UltraStarSong, format_bpm
+
+
+def detect_bpm(instrumental_path: Path) -> float:
+    import librosa
+    y, sr = librosa.load(str(instrumental_path), sr=22050, mono=True)
+    tempo, _ = librosa.beat.beat_track(y=y, sr=sr)
+    return float(np.atleast_1d(tempo)[0])
+
+
+def scale_bpm(bpm: float) -> float:
+    """Fold a tempo into UltraStar's usual [200, 400) file-BPM range."""
+    if not math.isfinite(bpm) or bpm <= 0:
+        raise ValueError(f"cannot scale bpm {bpm}")
+    while bpm < 200:
+        bpm *= 2
+    while bpm >= 400:
+        bpm /= 2
+    return bpm
+
+
+def to_ultrastar(notes: list[dict], breaks: list[float], file_bpm: float,
+                 headers: list[tuple[str, str]]) -> UltraStarSong:
+    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)
+
+    def beat(t: float) -> int:
+        return round((t - gap_ms / 1000) / spb)
+
+    # a line break at the same instant as a note belongs before it
+    events = [(t, 0, None) for t in breaks] + [(n["start"], 1, n) for n in notes]
+    events.sort(key=lambda e: e[:2])
+    body: list[Note | LineBreak] = []
+    # notes.py can only keep notes apart in seconds; quantising re-collides them,
+    # so the cursor keeps the emitted beats strictly ordered and non-overlapping
+    cursor = -math.inf
+    for t, is_note, n in events:
+        if not is_note:
+            b = max(beat(t), cursor)
+            body.append(LineBreak(beat=b))
+            cursor = b
+        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"]))
+            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)

src/songtrace/languages.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Language:
+    iso: str             # whisper / num2words language code
+    pyphen: str | None   # pyphen dictionary code, None if no dictionary exists
+
+
+LANGUAGES: dict[str, Language] = {
+    "english": Language("en", "en_US"),
+    "german": Language("de", "de_DE"),
+    "spanish": Language("es", "es"),
+    "french": Language("fr", "fr"),
+    "italian": Language("it", "it"),
+    "portuguese": Language("pt", "pt"),
+    "dutch": Language("nl", "nl_NL"),
+    "japanese": Language("ja", None),
+}

src/songtrace/lyrics.py

@@ -0,0 +1,44 @@
+import re
+from dataclasses import dataclass
+from num2words import num2words
+
+from .languages import LANGUAGES
+
+SECTION_RE = re.compile(r"^\s*[\[(].*[\])]\s*$")
+
+
+@dataclass
+class RefLyrics:
+    lines: list[list[str]]
+    words: list[str]
+    word_line_index: list[int]
+
+
+def normalize_lyrics(text: str) -> RefLyrics:
+    lines = []
+    for raw in text.splitlines():
+        if not raw.strip() or SECTION_RE.match(raw):
+            continue
+        lines.append(raw.split())
+    words, idx = [], []
+    for i, line in enumerate(lines):
+        words.extend(line)
+        idx.extend([i] * len(line))
+    return RefLyrics(lines, words, idx)
+
+
+def alignment_token(word: str, language: str | None = None) -> str:
+    entry = LANGUAGES.get((language or "english").lower())
+    lang = entry.iso if entry else "en"
+
+    def expand(m):
+        try:
+            return " " + num2words(int(m[0]), lang=lang) + " "
+        except NotImplementedError:
+            return " " + num2words(int(m[0])) + " "
+
+    word = word.replace("’", "'").replace("ʼ", "'")
+    word = re.sub(r"\d+", expand, word)
+    word = word.lower()
+    word = re.sub(r"[^a-z'À-ɏЀ-ӿ ]", "", word)
+    return re.sub(r"\s+", "", word)

src/songtrace/media.py

@@ -0,0 +1,23 @@
+import json
+import subprocess
+from pathlib import Path
+
+from .pipeline import PipelineError
+
+
+def ffmpeg(*args: str) -> None:
+    result = subprocess.run(["ffmpeg", "-y", *args], capture_output=True, text=True)
+    if result.returncode != 0:
+        raise PipelineError(f"ffmpeg failed: {result.stderr[-2000:]}")
+
+
+def ffprobe_codec(path: Path) -> tuple[str, str]:
+    result = subprocess.run(
+        ["ffprobe", "-v", "quiet", "-print_format", "json",
+         "-show_format", "-show_streams", str(path)],
+        capture_output=True, text=True)
+    if result.returncode != 0:
+        raise PipelineError(f"ffprobe failed on {path}")
+    data = json.loads(result.stdout)
+    video = next((s for s in data["streams"] if s["codec_type"] == "video"), {})
+    return data["format"]["format_name"], video.get("codec_name", "")

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

@@ -0,0 +1,190 @@
+import math
+from dataclasses import dataclass
+
+import numpy as np
+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
+SPLIT_SEMITONES = 0.8
+MIN_SEG_SEC = 0.05
+MIN_NOTE_SEC = 0.05      # alignment may hand us zero-length words
+HOP_SEC = 0.01           # pitch stage hop
+
+_SYLL_SEP = "\0"         # sentinel so literal hyphens survive syllabification
+
+
+@dataclass
+class TimedNote:
+    start: float
+    duration: float
+    pitch: int            # UltraStar semitone (0 = C4 = MIDI 60)
+    text: str             # display text incl. leading space / "~"
+    low_confidence: bool
+    line_index: int
+
+
+def hz_to_midi_float(hz: float) -> float:
+    return 69 + 12 * math.log2(hz / 440.0)
+
+
+def hz_to_ultrastar(hz: float) -> int:
+    return round(hz_to_midi_float(hz)) - 60
+
+
+def segment_span(times, f0, conf, start: float, end: float
+                 ) -> list[tuple[float, float, float]]:
+    """Voiced pitch segments within [start, end) as (start, end, median_midi)."""
+    mask = (times >= start) & (times < end) & (conf >= CONF_MASK) & (f0 > 0)
+    t = times[mask]
+    if len(t) == 0:
+        return []
+    midi = 69 + 12 * np.log2(f0[mask] / 440.0)
+    segs: list[tuple[float, float, float]] = []
+
+    def emit(a: int, b: int) -> None:
+        if float(t[b - 1]) - float(t[a]) + HOP_SEC >= MIN_SEG_SEC:
+            segs.append((float(t[a]), float(t[b - 1]) + HOP_SEC,
+                         float(np.median(midi[a:b]))))
+
+    seg_start, dev_start = 0, None
+    for i in range(1, len(t)):
+        stable_end = i if dev_start is None else dev_start
+        if abs(midi[i] - np.median(midi[seg_start:stable_end])) >= SPLIT_SEMITONES:
+            # only split once the deviation has held for MIN_SEG_SEC, so that
+            # short tracker glitches don't fragment a sustained note
+            if dev_start is None:
+                dev_start = i
+            elif t[i] - t[dev_start] + HOP_SEC >= MIN_SEG_SEC:
+                emit(seg_start, dev_start)
+                seg_start, dev_start = dev_start, None
+        else:
+            dev_start = None
+    emit(seg_start, len(t))
+    return segs
+
+
+def syllabify(word: str, language: str | None) -> list[str]:
+    entry = LANGUAGES.get((language or "english").lower())
+    code = entry.pyphen if entry else "en_US"
+    if code is None:
+        return [word]
+    try:
+        dic = pyphen.Pyphen(lang=code)
+    except KeyError:
+        return [word]
+    parts = [p for p in dic.inserted(word, hyphen=_SYLL_SEP).split(_SYLL_SEP) if p]
+    return parts or [word]
+
+
+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] = []
+    prev_line, prev_end = None, 0.0
+    for row in rows:
+        if prev_line is not None and row["line_index"] > prev_line:
+            breaks.append((prev_end + row["start"]) / 2)
+        line_initial = row["line_index"] != prev_line
+        prev_line, prev_end = row["line_index"], row["end"]
+        segs = segment_span(times, f0, conf, row["start"], row["end"])
+        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,
+                               row["line_index"]))
+            continue
+        low = row["score"] < LOW_SCORE
+        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,
+                               row["line_index"]))
+    _deoverlap(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, line_index: int) -> TimedNote:
+    return TimedNote(float(start), float(duration), int(pitch), text, low,
+                     int(line_index))
+
+
+def _deoverlap(notes: list[TimedNote]) -> None:
+    """Give every note a positive length without letting notes collide.
+
+    Notes are grown to MIN_NOTE_SEC (alignment hands us zero-length words, and
+    subdividing a short word by syllable makes very short slices) but only into
+    space the next note isn't using; where there is no space at all the rest of
+    the song is nudged later.
+    """
+    limits = [math.inf] * len(notes)
+    for i in range(len(notes) - 2, -1, -1):
+        limits[i] = (notes[i + 1].start if notes[i + 1].start > notes[i].start
+                     else limits[i + 1])
+    cursor = -math.inf
+    for note, limit in zip(notes, limits):
+        note.start = max(note.start, cursor)
+        room = limit - note.start
+        note.duration = (min(max(note.duration, MIN_NOTE_SEC), room)
+                         if room > 0 else MIN_NOTE_SEC)
+        cursor = note.start + note.duration
+
+
+def _text(syllable: str, index: int, line_initial: bool) -> str:
+    return syllable if index or line_initial else " " + syllable
+
+
+def _subdivide(segs, target: int):
+    """Cut segments into equal slices until there is one per syllable."""
+    parts = [1] * len(segs)
+    while sum(parts) < target:
+        i = max(range(len(segs)),
+                key=lambda j: (segs[j][1] - segs[j][0]) / parts[j])
+        parts[i] += 1
+    out = []
+    for (s, e, midi), n in zip(segs, parts):
+        step = (e - s) / n
+        out.extend((s + k * step, s + (k + 1) * step, midi) for k in range(n))
+    return out
+
+
+def _fmt(t: float) -> str:
+    return f"{int(t // 60)}:{int(t % 60):02d}"
+
+
+def _warnings(notes: list[TimedNote], dropped_lines=(), missing_spans=(),
+             ref_lines=()) -> 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 = []
+    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

@@ -0,0 +1,88 @@
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable
+
+from . import models
+from .config import Config
+
+class PipelineError(Exception):
+    pass
+
+@dataclass
+class SongInput:
+    title: str
+    artist: str
+    lyrics_text: str
+    youtube_url: str | None = None
+    video_path: Path | None = None
+    genre: str | None = None
+    year: int | None = None
+    language: str | None = None
+    cover_path: Path | None = None      # local file or URL already fetched by front-end
+    bpm_override: float | None = None
+
+@dataclass
+class Stage:
+    name: str
+    outputs: Callable[["Ctx"], list[Path]]
+    run: Callable[["Ctx"], None]
+
+@dataclass
+class Ctx:
+    inp: SongInput
+    cfg: Config
+    work: Path                          # per-song work dir (created)
+    log: Callable[[str], None]
+
+@dataclass
+class PipelineResult:
+    output_dir: Path
+    warnings: list[str] = field(default_factory=list)
+
+STAGE_ORDER = ["acquire", "separate", "transcribe", "align", "pitch", "notes", "grid", "package"]
+
+def song_slug(inp: SongInput) -> str:
+    name = f"{inp.artist} - {inp.title}"
+    return name.replace("/", "").replace("\0", "")
+
+def read_warnings(work: Path) -> list[str]:
+    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()
+
+def run_pipeline(inp: SongInput, cfg: Config, log=print,
+                 force_from: str | None = None,
+                 stages: list[Stage] | None = None) -> PipelineResult:
+    if stages is None:
+        stages = _real_stages()
+    names = [s.name for s in stages]
+    if force_from is not None and force_from not in names:
+        raise PipelineError(f"unknown stage {force_from!r}, expected one of {names}")
+    work = cfg.work_dir / song_slug(inp)
+    work.mkdir(parents=True, exist_ok=True)
+    ctx = Ctx(inp=inp, cfg=cfg, work=work, log=log)
+    forcing = False
+    for stage in stages:
+        if stage.name == force_from:
+            forcing = True
+        if not forcing and all(p.exists() for p in stage.outputs(ctx)):
+            log(f"[{stage.name}] cached, skipping")
+            continue
+        log(f"[{stage.name}] running")
+        # 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

@@ -0,0 +1,84 @@
+import shutil
+from pathlib import Path
+
+from .config import Config
+from .pipeline import STAGE_ORDER, PipelineError, SongInput, song_slug
+
+# The earliest stage that reads each SongInput field. Editing a field means every
+# stage from here onward is stale. Adding a field to SongInput without adding it
+# here would let an edit invalidate nothing at all, so tests pin this to the
+# dataclass.
+FIELD_STAGE = {
+    "youtube_url": "acquire",
+    "video_path": "acquire",
+    "language": "transcribe",
+    "lyrics_text": "align",
+    "title": "grid",
+    "artist": "grid",
+    "genre": "grid",
+    "year": "grid",
+    "bpm_override": "grid",
+    "cover_path": "package",
+}
+
+
+def changed_fields(old: SongInput, new: SongInput) -> list[str]:
+    return [f for f in FIELD_STAGE if getattr(old, f) != getattr(new, f)]
+
+
+def plan(old: SongInput, new: SongInput) -> str | None:
+    """The stage to restart from, or None when nothing changed.
+
+    None is not "do nothing": run_pipeline with no force_from resumes at the
+    first stage whose outputs are missing, which is exactly what a rerun wants.
+    """
+    changed = changed_fields(old, new)
+    if not changed:
+        return 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.
+
+    Nothing inside a work dir depends on the slug except song.txt, which `grid`
+    rewrites — and FIELD_STAGE sends title/artist edits to `grid`. So a retitle
+    costs a rename plus grid and package, not the whole GPU pipeline.
+    """
+    old_dir = cfg.work_dir / song_slug(old)
+    new_dir = cfg.work_dir / song_slug(new)
+    if old_dir == new_dir or not old_dir.exists():
+        return False
+    if new_dir.exists():
+        raise PipelineError(
+            f"a work folder already exists for {song_slug(new)!r}; "
+            "rename or remove it before rebuilding")
+    new_dir.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(old_dir), str(new_dir))
+    return True
+
+
+def superseded_output(old_dir: str | None, new_dir: str,
+                      output_root: Path) -> Path | None:
+    """The previous build's folder, when the rebuild replaced it under a new slug.
+
+    Returns None unless the path is strictly inside output_root, so a bad job
+    record cannot turn the caller's removal into an arbitrary delete.
+    """
+    if not old_dir:
+        return None
+    old, new = Path(old_dir).resolve(), Path(new_dir).resolve()
+    if old == new or output_root.resolve() not in old.parents:
+        return None
+    return old

src/songtrace/stages/__init__.py

@@ -0,0 +1,14 @@
+from ..pipeline import Stage
+from .acquire import acquire_stage
+from .align import align_stage
+from .grid import grid_stage
+from .notes import notes_stage
+from .package import package_stage
+from .pitch import pitch_stage
+from .separate import separate_stage
+from .transcribe import transcribe_stage
+
+
+def all_stages() -> list[Stage]:
+    return [acquire_stage(), separate_stage(), transcribe_stage(), align_stage(),
+            pitch_stage(), notes_stage(), grid_stage(), package_stage()]

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

@@ -0,0 +1,40 @@
+import json
+from pathlib import Path
+
+from .. import grid
+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())
+    meta = json.loads((ctx.work / "meta.json").read_text())
+    if ctx.inp.bpm_override is not None:
+        bpm = ctx.inp.bpm_override
+    else:
+        try:
+            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?")
+    slug = song_slug(ctx.inp)
+    video_ext = Path(meta["video_file"]).suffix
+    headers = [("TITLE", ctx.inp.title), ("ARTIST", ctx.inp.artist)]
+    if ctx.inp.language:
+        headers.append(("LANGUAGE", ctx.inp.language))
+    if ctx.inp.genre:
+        headers.append(("GENRE", ctx.inp.genre))
+    if ctx.inp.year:
+        headers.append(("YEAR", str(ctx.inp.year)))
+    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)
+    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")
+
+
+def grid_stage() -> Stage:
+    return Stage(name="grid",
+                 outputs=lambda ctx: [ctx.work / "song.txt"],
+                 run=_run)

src/songtrace/stages/notes.py

@@ -0,0 +1,33 @@
+import json
+from dataclasses import asdict
+
+import numpy as np
+
+from ..lyrics import normalize_lyrics
+from ..notes import build_notes
+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,
+        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,
+        "warnings": warnings,
+    }))
+
+
+def notes_stage() -> Stage:
+    return Stage(name="notes",
+                 outputs=lambda ctx: [ctx.work / "notes_sec.json"],
+                 run=_run)

src/songtrace/stages/package.py

@@ -0,0 +1,84 @@
+import json
+import shutil
+from pathlib import Path
+
+from PIL import Image, UnidentifiedImageError
+
+from ..media import ffmpeg, ffprobe_codec
+from ..pipeline import Ctx, Stage, song_slug
+from ..ultrastar import parse_ultrastar, serialize_ultrastar
+
+GOOD_VIDEO = {("webm", "vp9"), ("webm", "vp8"),
+              ("mov,mp4,m4a,3gp,3g2,mj2", "h264")}
+
+
+def prepare_cover(src: Path, dest_jpg: Path) -> None:
+    img = Image.open(src).convert("RGB")
+    side = min(img.size)
+    left = (img.width - side) // 2
+    top = (img.height - side) // 2
+    img = img.crop((left, top, left + side, top + side))
+    if side > 800:
+        img = img.resize((800, 800))
+    img.save(dest_jpg, "JPEG", quality=90)
+
+
+def _set_header(txt_path: Path, key: str, value: str | None) -> None:
+    song = parse_ultrastar(txt_path.read_text(encoding="utf-8"))
+    replaced = False
+    headers = []
+    for k, v in song.headers:
+        if k.upper() == key.upper():
+            replaced = True
+            if value is not None:
+                headers.append((key, value))
+        else:
+            headers.append((k, v))
+    if value is not None and not replaced:
+        headers.append((key, value))
+    song.headers = headers
+    txt_path.write_text(serialize_ultrastar(song), encoding="utf-8")
+
+
+def _run(ctx: Ctx) -> None:
+    slug = song_slug(ctx.inp)
+    out = ctx.cfg.output_dir / slug
+    out.mkdir(parents=True, exist_ok=True)
+    txt = out / f"{slug}.txt"
+    shutil.copyfile(ctx.work / "song.txt", txt)
+    ffmpeg("-i", str(ctx.work / "audio.wav"), "-b:a", "320k",
+           str(out / f"{slug}.mp3"))
+    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:
+        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", "-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"):
+        cover_src = ctx.work / meta["thumbnail"]
+    cover_ok = False
+    if cover_src and Path(cover_src).exists():
+        try:
+            prepare_cover(Path(cover_src), out / f"{slug}.jpg")
+            cover_ok = True
+        except UnidentifiedImageError:
+            ctx.log("cover file is not a valid image; dropping #COVER header")
+    else:
+        ctx.log("no cover available; dropping #COVER header")
+    if not cover_ok:
+        _set_header(txt, "COVER", None)
+    (ctx.work / "package.done").write_text("")
+
+
+def package_stage() -> Stage:
+    def outputs(ctx: Ctx):
+        return [ctx.work / "package.done"]
+    return Stage(name="package", outputs=outputs, run=_run)

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/separate.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+import soundfile as sf
+
+from ..pipeline import Ctx, Stage
+
+
+def separate_audio(audio_path: Path, model: str, device: str):
+    from demucs.api import Separator
+    separator = Separator(model=model, device=device)
+    _, stems = separator.separate_audio_file(audio_path)
+    return stems
+
+
+def _run(ctx: Ctx) -> None:
+    stems = separate_audio(ctx.work / "audio.wav",
+                           ctx.cfg.demucs_model, ctx.cfg.device)
+    vocals = stems["vocals"]
+    others = [t for name, t in stems.items() if name != "vocals"]
+    instrumental = sum(others[1:], start=others[0])
+    sf.write(ctx.work / "vocals.wav", vocals.cpu().numpy().T, 44100)
+    sf.write(ctx.work / "instrumental.wav", instrumental.cpu().numpy().T, 44100)
+
+
+def separate_stage() -> Stage:
+    return Stage(
+        name="separate",
+        outputs=lambda ctx: [ctx.work / "vocals.wav", ctx.work / "instrumental.wav"],
+        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/fonts/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git) ChakraPetch-LightItalic.ttf: Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git) ChakraPetch-Regular.ttf: Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git) ChakraPetch-Italic.ttf: Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git) ChakraPetch-Medium.ttf: Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git) ChakraPetch-MediumItalic.ttf: Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git) ChakraPetch-SemiBold.ttf: Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git) ChakraPetch-SemiBoldItalic.ttf: Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git) ChakraPetch-Bold.ttf: Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git) ChakraPetch-BoldItalic.ttf: Copyright 2018 The Chakra Petch Project Authors (https://github.com/m4rc1e/Chakra-Petch.git)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

src/songtrace/ultrastar.py

@@ -0,0 +1,73 @@
+import re
+from dataclasses import dataclass
+
+NOTE_RE = re.compile(r"^([:*FRG]) (-?\d+) (\d+) (-?\d+) (.*)$")
+
+
+@dataclass
+class Note:
+    kind: str
+    beat: int
+    length: int
+    pitch: int
+    text: str
+
+
+@dataclass
+class LineBreak:
+    beat: int
+
+
+@dataclass
+class UltraStarSong:
+    headers: list[tuple[str, str]]
+    body: list[Note | LineBreak]
+
+
+def parse_ultrastar(text: str) -> UltraStarSong:
+    headers, body = [], []
+    for line in text.splitlines():
+        line = line.rstrip("\r")
+        if not line.strip():
+            continue
+        if line.startswith("#"):
+            key, _, value = line[1:].partition(":")
+            headers.append((key, value))
+        elif line.startswith("E"):
+            break
+        elif line.startswith("-"):
+            nums = line[1:].split()
+            body.append(LineBreak(beat=int(nums[0])))
+        else:
+            m = NOTE_RE.match(line)
+            if m:
+                body.append(Note(m[1], int(m[2]), int(m[3]), int(m[4]), m[5]))
+    return UltraStarSong(headers, body)
+
+
+def serialize_ultrastar(song: UltraStarSong) -> str:
+    out = [f"#{k}:{v}" for k, v in song.headers]
+    for item in song.body:
+        if isinstance(item, LineBreak):
+            out.append(f"- {item.beat}")
+        else:
+            out.append(f"{item.kind} {item.beat} {item.length} {item.pitch} {item.text}")
+    out.append("E")
+    return "\n".join(out) + "\n"
+
+
+def get_header(song: UltraStarSong, key: str) -> str | None:
+    for k, v in song.headers:
+        if k.upper() == key.upper():
+            return v
+    return None
+
+
+def format_bpm(bpm: float) -> str:
+    if bpm == int(bpm):
+        return str(int(bpm))
+    return f"{bpm:.2f}".replace(".", ",")
+
+
+def parse_bpm(value: str) -> float:
+    return float(value.replace(",", "."))

src/songtrace/web.py

@@ -0,0 +1,505 @@
+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
+
+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 .lyrics import normalize_lyrics
+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 — 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 _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()
+    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]
+
+            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)
+                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,
+                 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 / "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"]})
+        lines = [{"index": i, "text": " ".join(words), "dropped": i in dropped,
+                  "notes": by_line.get(i, []), "words": words_by_line.get(i, [])}
+                 for i, words in enumerate(ref.lines)]
+        media = {kind: _resolve_media(job, header) is not None
+                 for kind, header in MEDIA_HEADERS.items()}
+        return {"lines": lines, "missing_spans": missing_spans, "media": media}
+
+    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/test_acquire.py

@@ -0,0 +1,202 @@
+import json
+from pathlib import Path
+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)
+    cfg = Config(whisper_url="http://x/v1", work_dir=tmp_path)
+    work = tmp_path / "A - T"
+    work.mkdir()
+    return Ctx(inp=inp, cfg=cfg, work=work, log=lambda m: None)
+
+def test_local_video(tmp_path, monkeypatch):
+    src = tmp_path / "in.mp4"
+    src.write_bytes(b"fake")
+    calls = []
+    monkeypatch.setattr(acquire, "ffmpeg", lambda *a: calls.append(a))
+    ctx = make_ctx(tmp_path, video_path=src)
+    acquire.acquire_stage().run(ctx)
+    meta = json.loads((ctx.work / "meta.json").read_text())
+    assert meta["video_file"] == "source_video.mp4"
+    assert (ctx.work / "source_video.mp4").read_bytes() == b"fake"
+    assert any("audio.wav" in str(a[-1]) for a in calls)
+
+def test_youtube(tmp_path, monkeypatch):
+    def fake_dl(url, dest, cfg, log):
+        video = dest / "source_video.webm"
+        video.write_bytes(b"v")
+        thumb = dest / "source_video.jpg"
+        thumb.write_bytes(b"t")
+        return video, thumb
+    monkeypatch.setattr(acquire, "download_youtube", fake_dl)
+    monkeypatch.setattr(acquire, "ffmpeg", lambda *a: None)
+    ctx = make_ctx(tmp_path, youtube_url="https://yt/x")
+    acquire.acquire_stage().run(ctx)
+    meta = json.loads((ctx.work / "meta.json").read_text())
+    assert meta["video_file"] == "source_video.webm"
+    assert meta["thumbnail"] == "source_video.jpg"
+
+def test_outputs_are_meta_and_audio(tmp_path):
+    """_require_source in web.py hardcodes these filenames; pin them here."""
+    ctx = make_ctx(tmp_path, youtube_url="https://yt/x")
+    outputs = acquire.acquire_stage().outputs(ctx)
+    assert [p.name for p in outputs] == ["meta.json", "audio.wav"]
+
+def test_requires_exactly_one_source(tmp_path):
+    import pytest
+    from songtrace.pipeline import PipelineError
+    ctx = make_ctx(tmp_path)
+    with pytest.raises(PipelineError):
+        acquire.acquire_stage().run(ctx)
+
+def test_classify_ordinary_webm_and_jpg(tmp_path):
+    (tmp_path / "source_video.webm").write_bytes(b"v")
+    (tmp_path / "source_video.jpg").write_bytes(b"t")
+    video, thumb = acquire._classify_downloads(tmp_path)
+    assert video.name == "source_video.webm"
+    assert thumb.name == "source_video.jpg"
+
+def test_classify_unexpected_thumbnail_extension(tmp_path):
+    (tmp_path / "source_video.webm").write_bytes(b"v")
+    (tmp_path / "source_video.avif").write_bytes(b"t")
+    video, thumb = acquire._classify_downloads(tmp_path)
+    assert video.name == "source_video.webm"
+    assert thumb.name == "source_video.avif"
+
+def test_classify_no_thumbnail(tmp_path):
+    (tmp_path / "source_video.mp4").write_bytes(b"v")
+    video, thumb = acquire._classify_downloads(tmp_path)
+    assert video.name == "source_video.mp4"
+    assert thumb is None
+
+def test_classify_no_video_raises(tmp_path):
+    import pytest
+    from songtrace.pipeline import PipelineError
+    (tmp_path / "source_video.jpg").write_bytes(b"t")
+    with pytest.raises(PipelineError):
+        acquire._classify_downloads(tmp_path)
+
+def test_classify_picks_largest_video_when_multiple(tmp_path):
+    (tmp_path / "source_video.f137.mp4").write_bytes(b"small")
+    (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

@@ -0,0 +1,237 @@
+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: [])
+
+
+LYRICS = "it's one two three\nfour five six seven eight"
+
+
+def make_ctx(tmp_path, lyrics=LYRICS, transcript=None):
+    work = tmp_path / "w"
+    work.mkdir(exist_ok=True)
+    if transcript is None:
+        transcript = [{"start": 1.0, "end": 4.0,
+                       "text": "it's one two three four five six seven eight"}]
+    (work / "transcript.json").write_text(json.dumps(transcript))
+    inp = SongInput(title="T", artist="A", lyrics_text=lyrics)
+    return Ctx(inp=inp, cfg=Config(whisper_url="u", device="cpu"),
+               work=work, log=lambda m: None)
+
+
+def fake_align(vocals_path, start, end, tokens, device):
+    step = (end - start) / len(tokens)
+    return [(start + i * step, start + (i + 1) * step, 0.9)
+            for i in range(len(tokens))]
+
+
+def run_align(tmp_path, monkeypatch, lyrics=LYRICS, transcript=None):
+    monkeypatch.setattr(align, "force_align_section", fake_align)
+    ctx = make_ctx(tmp_path, lyrics, transcript)
+    align.align_stage().run(ctx)
+    return json.loads((ctx.work / "alignment.json").read_text())
+
+
+def check_invariants(rows, lyrics):
+    ref = normalize_lyrics(lyrics)
+    assert [r["word"] for r in rows] == ref.words
+    assert [r["line_index"] for r in rows] == ref.word_line_index
+    prev = 0.0
+    for r in rows:
+        assert r["start"] is not None and r["end"] is not None
+        assert prev <= r["start"] <= r["end"]
+        prev = r["end"]
+
+
+def test_alignment_covers_all_words(tmp_path, monkeypatch):
+    rows = run_align(tmp_path, monkeypatch)
+    assert [r["word"] for r in rows] == \
+        ["it's", "one", "two", "three", "four", "five", "six", "seven", "eight"]
+    assert rows[0]["line_index"] == 0 and rows[-1]["line_index"] == 1
+    starts = [r["start"] for r in rows]
+    assert starts == sorted(starts)
+
+
+def test_mismatched_lyrics_fail(tmp_path, monkeypatch):
+    monkeypatch.setattr(align, "force_align_section", fake_align)
+    ctx = make_ctx(tmp_path, lyrics="totally unrelated nonsense words banana")
+    with pytest.raises(PipelineError, match="similarity"):
+        align.align_stage().run(ctx)
+
+
+def test_unalignable_word_interpolated(tmp_path, monkeypatch):
+    lyrics = "it's one ... three\nfour five six seven eight"
+    rows = run_align(tmp_path, monkeypatch, lyrics)
+    dots = next(r for r in rows if r["word"] == "...")
+    assert dots["score"] == 0.0
+    prev = next(r for r in rows if r["word"] == "one")
+    nxt = next(r for r in rows if r["word"] == "three")
+    assert prev["end"] <= dots["start"] <= dots["end"] <= nxt["start"] + 1e-6
+    check_invariants(rows, lyrics)
+
+
+def test_leading_unalignable_word(tmp_path, monkeypatch):
+    lyrics = "... one two three\nfour five six seven eight"
+    rows = run_align(tmp_path, monkeypatch, lyrics)
+    assert rows[0]["word"] == "..." and rows[0]["score"] == 0.0
+    assert rows[0]["start"] >= 0.0
+    assert rows[0]["end"] <= rows[1]["start"] + 1e-6
+    check_invariants(rows, lyrics)
+
+
+def test_trailing_unalignable_word(tmp_path, monkeypatch):
+    lyrics = "it's one two three\nfour five six seven ..."
+    rows = run_align(tmp_path, monkeypatch, lyrics)
+    assert rows[-1]["word"] == "..." and rows[-1]["score"] == 0.0
+    assert rows[-2]["end"] <= rows[-1]["start"]
+    check_invariants(rows, lyrics)
+
+
+def test_consecutive_unalignable_words(tmp_path, monkeypatch):
+    lyrics = "it's one ... ... three\nfour five six seven eight"
+    rows = run_align(tmp_path, monkeypatch, lyrics)
+    dots = [r for r in rows if r["word"] == "..."]
+    assert len(dots) == 2
+    assert all(r["score"] == 0.0 for r in dots)
+    assert dots[0]["end"] <= dots[1]["start"]
+    check_invariants(rows, lyrics)
+
+
+def test_all_words_unalignable_in_section(tmp_path, monkeypatch):
+    lyrics = "... ...\n... ..."
+    transcript = [{"start": 1.0, "end": 4.0, "text": "..."}]
+    monkeypatch.setattr(align, "force_align_section", fake_align)
+    ctx = make_ctx(tmp_path, lyrics, transcript)
+    align.align_stage().run(ctx)
+    rows = json.loads((ctx.work / "alignment.json").read_text())
+    check_invariants(rows, lyrics)
+    assert all(r["score"] == 0.0 for r in rows)
+    assert rows[-1]["end"] <= 5.0
+
+
+def test_non_chronological_transcript(tmp_path, monkeypatch):
+    transcript = [{"start": 30.0, "end": 33.0, "text": "four five six seven eight"},
+                  {"start": 1.0, "end": 4.0, "text": "it's one two three"}]
+    rows = run_align(tmp_path, monkeypatch, transcript=transcript)
+    check_invariants(rows, LYRICS)
+    assert len({r["start"] for r in rows}) == len(rows)
+    assert rows[3]["end"] <= 5.0
+    assert rows[4]["start"] >= 29.0
+
+
+def test_inverted_section_does_not_collapse(tmp_path, monkeypatch):
+    monkeypatch.setattr(align, "vocal_sections", lambda segments: [(29.0, 5.0)])
+    rows = run_align(tmp_path, monkeypatch)
+    check_invariants(rows, LYRICS)
+    assert len({r["start"] for r in rows}) == len(rows)
+    assert rows[0]["start"] >= 5.0 and rows[-1]["end"] <= 29.0
+
+
+def test_words_split_across_sections(tmp_path, monkeypatch):
+    transcript = [{"start": 1.0, "end": 4.0, "text": "it's one two three"},
+                  {"start": 30.0, "end": 33.0, "text": "four five six seven eight"}]
+    rows = run_align(tmp_path, monkeypatch, transcript=transcript)
+    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

@@ -0,0 +1,116 @@
+import os
+
+import pytest
+
+import songtrace.cli as cli
+from songtrace.config import Config
+from songtrace.pipeline import PipelineError, PipelineResult
+
+
+def setup_cfg(monkeypatch, tmp_path):
+    monkeypatch.setattr(cli, "load_config",
+                        lambda path=None: Config(whisper_url="u"))
+
+def test_make_success(tmp_path, monkeypatch, capsys):
+    setup_cfg(monkeypatch, tmp_path)
+    lyrics = tmp_path / "l.txt"
+    lyrics.write_text("la la")
+    captured = {}
+    def fake_run(inp, cfg, log=print, force_from=None, stages=None):
+        captured["inp"] = inp
+        captured["force_from"] = force_from
+        return PipelineResult(output_dir=tmp_path / "out", warnings=["w1"])
+    monkeypatch.setattr(cli, "run_pipeline", fake_run)
+    rc = cli.main(["make", "--title", "T", "--artist", "A",
+                   "--lyrics", str(lyrics), "--youtube", "http://y",
+                   "--force-from", "align"])
+    assert rc == 0
+    assert captured["inp"].lyrics_text == "la la"
+    assert captured["force_from"] == "align"
+    out = capsys.readouterr().out
+    assert "w1" in out and str(tmp_path / "out") in out
+
+def test_make_pipeline_error(tmp_path, monkeypatch, capsys):
+    setup_cfg(monkeypatch, tmp_path)
+    lyrics = tmp_path / "l.txt"
+    lyrics.write_text("x")
+    def boom(*a, **kw):
+        raise PipelineError("lyrics don't match")
+    monkeypatch.setattr(cli, "run_pipeline", boom)
+    rc = cli.main(["make", "--title", "T", "--artist", "A",
+                   "--lyrics", str(lyrics), "--youtube", "http://y"])
+    assert rc == 1
+    assert "lyrics don't match" in capsys.readouterr().err
+
+def test_make_requires_one_source(tmp_path, monkeypatch, capsys):
+    setup_cfg(monkeypatch, tmp_path)
+    lyrics = tmp_path / "l.txt"
+    lyrics.write_text("x")
+    rc = cli.main(["make", "--title", "T", "--artist", "A",
+                   "--lyrics", str(lyrics)])
+    assert rc != 0
+
+def test_make_rejects_zero_bpm(tmp_path, monkeypatch, capsys):
+    setup_cfg(monkeypatch, tmp_path)
+    lyrics = tmp_path / "l.txt"
+    lyrics.write_text("x")
+    try:
+        cli.main(["make", "--title", "T", "--artist", "A",
+                  "--lyrics", str(lyrics), "--youtube", "http://y",
+                  "--bpm", "0"])
+        assert False, "expected SystemExit"
+    except SystemExit as e:
+        assert e.code != 0
+    assert "--bpm" in capsys.readouterr().err
+
+def test_make_rejects_negative_bpm(tmp_path, monkeypatch, capsys):
+    setup_cfg(monkeypatch, tmp_path)
+    lyrics = tmp_path / "l.txt"
+    lyrics.write_text("x")
+    try:
+        cli.main(["make", "--title", "T", "--artist", "A",
+                  "--lyrics", str(lyrics), "--youtube", "http://y",
+                  "--bpm", "-120"])
+        assert False, "expected SystemExit"
+    except SystemExit as e:
+        assert e.code != 0
+    assert "--bpm" in capsys.readouterr().err
+
+def test_make_reports_missing_lyrics_file(tmp_path, monkeypatch, capsys):
+    setup_cfg(monkeypatch, tmp_path)
+    def boom(*a, **kw):
+        raise AssertionError("run_pipeline must not run with an unreadable lyrics file")
+    monkeypatch.setattr(cli, "run_pipeline", boom)
+    rc = cli.main(["make", "--title", "T", "--artist", "A",
+                   "--lyrics", str(tmp_path / "missing.txt"), "--youtube", "http://y"])
+    assert rc != 0
+    assert "--lyrics" in capsys.readouterr().err
+
+@pytest.mark.skipif(os.geteuid() == 0, reason="root ignores file permissions")
+def test_make_reports_unreadable_lyrics_file(tmp_path, monkeypatch, capsys):
+    setup_cfg(monkeypatch, tmp_path)
+    lyrics = tmp_path / "l.txt"
+    lyrics.write_text("x")
+    lyrics.chmod(0o000)
+    def boom(*a, **kw):
+        raise AssertionError("run_pipeline must not run with an unreadable lyrics file")
+    monkeypatch.setattr(cli, "run_pipeline", boom)
+    try:
+        rc = cli.main(["make", "--title", "T", "--artist", "A",
+                       "--lyrics", str(lyrics), "--youtube", "http://y"])
+    finally:
+        lyrics.chmod(0o644)
+    assert rc != 0
+    assert "--lyrics" in capsys.readouterr().err
+
+def test_make_reports_undecodable_lyrics_file(tmp_path, monkeypatch, capsys):
+    setup_cfg(monkeypatch, tmp_path)
+    lyrics = tmp_path / "l.txt"
+    lyrics.write_bytes(b"\xff\xfe\x00bad")
+    def boom(*a, **kw):
+        raise AssertionError("run_pipeline must not run with undecodable lyrics")
+    monkeypatch.setattr(cli, "run_pipeline", boom)
+    rc = cli.main(["make", "--title", "T", "--artist", "A",
+                   "--lyrics", str(lyrics), "--youtube", "http://y"])
+    assert rc != 0
+    assert "--lyrics" in capsys.readouterr().err

tests/test_config.py

@@ -0,0 +1,40 @@
+import pytest
+from pathlib import Path
+from songtrace.config import Config, load_config
+
+
+def test_load_minimal(tmp_path):
+    cfg_file = tmp_path / "config.toml"
+    cfg_file.write_text('whisper_url = "http://w:9000/v1"\n')
+    cfg = load_config(cfg_file)
+    assert cfg.whisper_url == "http://w:9000/v1"
+    assert cfg.demucs_model == "htdemucs_ft"
+
+
+def test_paths_and_overrides(tmp_path):
+    cfg_file = tmp_path / "config.toml"
+    cfg_file.write_text(
+        'whisper_url = "http://w/v1"\noutput_dir = "/srv/songs"\nport = 9999\n'
+    )
+    cfg = load_config(cfg_file)
+    assert cfg.output_dir == Path("/srv/songs")
+    assert cfg.port == 9999
+
+
+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("SONGTRACE_CONFIG", str(cfg_file))
+    assert load_config().whisper_url == "http://env/v1"
+
+
+def test_unknown_key_rejected(tmp_path):
+    cfg_file = tmp_path / "c.toml"
+    cfg_file.write_text('whisper_url = "x"\nwhipser_model = "typo"\n')
+    with pytest.raises(ValueError, match="whipser_model"):
+        load_config(cfg_file)
+
+
+def test_missing_file(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        load_config(tmp_path / "nope.toml")

tests/test_e2e.py

@@ -0,0 +1,30 @@
+import os
+import shutil
+
+import pytest
+
+requires_full = pytest.mark.skipif(
+    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 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["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 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_grid.py

@@ -0,0 +1,259 @@
+import json
+
+import numpy as np
+import pytest
+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,
+)
+
+
+def note(start, duration, pitch=0, text="la"):
+    return {"start": start, "duration": duration, "pitch": pitch, "text": text,
+            "low_confidence": False}
+
+
+def assert_ordered(body):
+    """Beats never go backwards and no two notes share a beat."""
+    cursor = None
+    for item in body:
+        if cursor is not None:
+            assert item.beat >= cursor
+        cursor = item.beat + (0 if isinstance(item, LineBreak) else item.length)
+    notes = [i for i in body if isinstance(i, Note)]
+    for a, b in zip(notes, notes[1:]):
+        assert a.beat + a.length <= b.beat
+    assert all(n.length >= 1 for n in notes)
+
+
+def test_scale_bpm():
+    assert scale_bpm(128.0) == 256.0
+    assert scale_bpm(64.0) == 256.0
+    assert scale_bpm(250.0) == 250.0
+    assert scale_bpm(450.0) == 225.0
+
+
+@pytest.mark.parametrize("bpm", [0.0, -120.0, float("inf"), float("nan")])
+def test_scale_bpm_rejects_unusable_tempo(bpm):
+    with pytest.raises(ValueError):
+        scale_bpm(bpm)
+
+
+def test_to_ultrastar_rejects_empty_notes():
+    with pytest.raises(ValueError):
+        to_ultrastar([], [], 240.0, [])
+
+
+def test_to_ultrastar_conversion():
+    notes = [note(2.0, 0.5, 3, "la"), note(2.6, 0.25, 5, " la")]
+    song = to_ultrastar(notes, breaks=[2.55], file_bpm=240.0,
+                        headers=[("TITLE", "T")])
+    # spb = 60/(4*240) = 0.0625s; gap = 2000ms
+    assert get_header(song, "GAP") == "2000"
+    assert get_header(song, "BPM") == "240"
+    assert song.headers[0] == ("TITLE", "T")
+    n0, br, n1 = song.body
+    assert n0 == Note(kind=":", beat=0, length=8, pitch=3, text="la")
+    assert br == LineBreak(beat=9)          # (2.55-2.0)/0.0625 = 8.8 -> 9
+    assert n1.beat == 10 and n1.length == 4
+
+
+def test_min_length_one():
+    song = to_ultrastar([note(1.0, 0.001, 0, "x")], [], 240.0, [])
+    assert song.body[0].length == 1
+
+
+def test_fractional_bpm_header():
+    song = to_ultrastar([note(0.0, 1.0)], [], 232.5, [])
+    assert get_header(song, "BPM") == "232,50"
+
+
+def test_beat_cursor_separates_notes_quantised_onto_one_beat():
+    notes = [note(1.0, 0.01, 0, "a"), note(1.01, 0.01, 1, "b"),
+             note(1.02, 0.01, 2, "c")]
+    song = to_ultrastar(notes, [], 240.0, [])   # all three round to beat 0
+    assert [n.beat for n in song.body] == [0, 1, 2]
+    assert [n.length for n in song.body] == [1, 1, 1]
+    assert_ordered(song.body)
+
+
+def test_beat_cursor_preserves_onsets_that_do_not_collide():
+    notes = [note(0.0, 0.5), note(1.0, 0.5), note(2.0, 0.5)]
+    song = to_ultrastar(notes, [], 240.0, [])
+    assert [n.beat for n in song.body] == [0, 16, 32]
+
+
+def test_line_break_pushed_past_the_preceding_note():
+    notes = [note(0.0, 0.56), note(0.57, 0.1)]
+    song = to_ultrastar(notes, [0.51], 240.0, [])   # break rounds to beat 8
+    n0, br, n1 = song.body
+    assert n0.beat + n0.length == 9
+    assert br == LineBreak(beat=9)
+    assert n1.beat >= br.beat
+    assert_ordered(song.body)
+
+
+def test_line_break_on_a_note_start_precedes_that_note():
+    """No gap across a line boundary puts the break exactly on the next onset."""
+    notes = [note(0.0, 0.5, 0, "end"), note(0.5, 0.5, 2, "New")]
+    song = to_ultrastar(notes, [0.5], 240.0, [])
+    assert song.body[1] == LineBreak(beat=8)
+    assert [n.text for n in song.body if isinstance(n, Note)] == ["end", "New"]
+    assert_ordered(song.body)
+
+
+def test_line_break_not_after_the_following_note():
+    notes = [note(0.0, 0.02, 0, "a"), note(0.03, 0.02, 1, "b")]
+    song = to_ultrastar(notes, [0.025], 240.0, [])
+    br = song.body[1]
+    assert isinstance(br, LineBreak)
+    assert br.beat <= song.body[2].beat
+    assert_ordered(song.body)
+
+
+def sung_words(rng):
+    """Words cut into equal syllable slices, the way build_notes emits them."""
+    notes, breaks, t = [], [], 1.7
+    for i in range(60):
+        word = float(rng.uniform(0.05, 0.6))
+        sylls = int(rng.integers(1, 4))
+        for k in range(sylls):
+            notes.append(note(t + k * word / sylls, word / sylls,
+                              int(rng.integers(-12, 12))))
+        t += word + float(rng.uniform(0.0, 0.4))
+        if i % 5 == 4:
+            breaks.append(t - 0.05)
+    return notes, breaks
+
+
+@pytest.mark.parametrize("bpm", [200.0, 300.0, 399.0])
+def test_no_overlap_on_realistic_input(bpm):
+    rng = np.random.default_rng(7)
+    moved = 0
+    for _ in range(20):
+        notes, breaks = sung_words(rng)
+        song = to_ultrastar(notes, breaks, bpm, [])
+        assert len(song.body) == len(notes) + len(breaks)
+        assert song.body[0].beat == 0
+        assert_ordered(song.body)
+        spb = 60 / (4 * bpm)
+        emitted = [n for n in song.body if isinstance(n, Note)]
+        moved += sum(1 for n, src in zip(emitted, notes)
+                     if n.beat != round((src["start"] - notes[0]["start"]) / spb))
+    assert moved > 0        # otherwise the fuzz never exercises the beat cursor
+
+
+def write_work(work, video="source_video.webm"):
+    work.mkdir()
+    (work / "notes_sec.json").write_text(json.dumps({
+        "notes": [note(1.0, 0.5, 0, "la"), note(2.0, 0.5, 2, "la")],
+        "breaks": [1.75],
+        "warnings": [],
+    }))
+    (work / "meta.json").write_text(json.dumps(
+        {"video_file": video, "thumbnail": "source_video.jpg"}))
+
+
+def make_ctx(work, **kwargs):
+    inp = SongInput(title="Song", artist="Band", lyrics_text="x", **kwargs)
+    return Ctx(inp=inp, cfg=Config(whisper_url="u", creator="me"), work=work,
+               log=lambda m: None)
+
+
+def test_grid_stage_writes_song_txt(tmp_path, monkeypatch):
+    work = tmp_path / "w"
+    write_work(work)
+    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"]
+    stage.run(ctx)
+    song = parse_ultrastar((work / "song.txt").read_text(encoding="utf-8"))
+    assert [k for k, _ in song.headers] == [
+        "TITLE", "ARTIST", "LANGUAGE", "GENRE", "YEAR", "CREATOR",
+        "MP3", "COVER", "VIDEO", "BPM", "GAP"]
+    assert get_header(song, "BPM") == "240"        # 120 doubled into range
+    assert get_header(song, "GAP") == "1000"
+    assert get_header(song, "MP3") == "Band - Song.mp3"
+    assert get_header(song, "COVER") == "Band - Song.jpg"
+    assert get_header(song, "VIDEO") == "Band - Song.webm"
+    assert [n.text for n in song.body if isinstance(n, Note)] == ["la", "la"]
+    assert_ordered(song.body)
+
+
+def test_grid_stage_omits_optional_headers(tmp_path, monkeypatch):
+    work = tmp_path / "w"
+    write_work(work, video="source_video.mp4")
+    monkeypatch.setattr(grid_stage_mod.grid, "detect_bpm", lambda p: 210.0)
+    ctx = make_ctx(work)
+    grid_stage_mod.grid_stage().run(ctx)
+    song = parse_ultrastar((work / "song.txt").read_text(encoding="utf-8"))
+    assert [k for k, _ in song.headers] == [
+        "TITLE", "ARTIST", "CREATOR", "MP3", "COVER", "VIDEO", "BPM", "GAP"]
+    assert get_header(song, "VIDEO") == "Band - Song.mp4"
+    assert get_header(song, "CREATOR") == "me"
+
+
+def test_grid_stage_uses_bpm_override(tmp_path, monkeypatch):
+    work = tmp_path / "w"
+    write_work(work)
+
+    def boom(path):
+        raise AssertionError("detect_bpm must not run with an override")
+
+    monkeypatch.setattr(grid_stage_mod.grid, "detect_bpm", boom)
+    ctx = make_ctx(work, bpm_override=333.0)
+    grid_stage_mod.grid_stage().run(ctx)
+    song = parse_ultrastar((work / "song.txt").read_text(encoding="utf-8"))
+    assert get_header(song, "BPM") == "333"
+
+
+def test_grid_stage_honours_zero_bpm_override(tmp_path, monkeypatch):
+    """bpm_override=0.0 must not be mistaken for 'not provided' (falsy-zero bug)."""
+    work = tmp_path / "w"
+    write_work(work)
+
+    def boom(path):
+        raise AssertionError("detect_bpm must not run with an explicit override")
+
+    monkeypatch.setattr(grid_stage_mod.grid, "detect_bpm", boom)
+    captured = {}
+
+    def fake_to_ultrastar(notes, breaks, file_bpm, headers):
+        captured["bpm"] = file_bpm
+        return to_ultrastar(notes, breaks, 240.0, headers)
+
+    monkeypatch.setattr(grid_stage_mod.grid, "to_ultrastar", fake_to_ultrastar)
+    ctx = make_ctx(work, bpm_override=0.0)
+    grid_stage_mod.grid_stage().run(ctx)
+    assert captured["bpm"] == 0.0
+
+
+def test_grid_stage_reports_unusable_tempo_as_pipeline_error(tmp_path, monkeypatch):
+    work = tmp_path / "w"
+    write_work(work)
+    monkeypatch.setattr(grid_stage_mod.grid, "detect_bpm", lambda p: 0.0)
+    ctx = make_ctx(work)
+    with pytest.raises(PipelineError, match="tempo"):
+        grid_stage_mod.grid_stage().run(ctx)
+
+
+def test_grid_stage_reports_no_notes_as_pipeline_error(tmp_path, monkeypatch):
+    work = tmp_path / "w"
+    work.mkdir()
+    (work / "notes_sec.json").write_text(json.dumps(
+        {"notes": [], "breaks": [], "warnings": []}))
+    (work / "meta.json").write_text(json.dumps(
+        {"video_file": "source_video.webm", "thumbnail": "source_video.jpg"}))
+    monkeypatch.setattr(grid_stage_mod.grid, "detect_bpm", lambda p: 120.0)
+    ctx = make_ctx(work)
+    with pytest.raises(PipelineError, match="no notes"):
+        grid_stage_mod.grid_stage().run(ctx)
+
+
+def test_grid_stage_registered():
+    names = [s.name for s in all_stages()]
+    assert names[-1] == "package" and names[-2] == "grid"

tests/test_lyrics.py

@@ -0,0 +1,40 @@
+from songtrace.lyrics import normalize_lyrics, alignment_token
+
+RAW = """[Verse 1]
+It's one two three
+
+[Chorus]
+Whoa, la la o' la
+Count me up to 7 times
+"""
+
+
+def test_normalize_strips_sections_and_blanks():
+    ref = normalize_lyrics(RAW)
+    assert ref.lines == [
+        ["It's", "one", "two", "three"],
+        ["Whoa,", "la", "la", "o'", "la"],
+        ["Count", "me", "up", "to", "7", "times"],
+    ]
+    assert ref.words[0] == "It's"
+    assert ref.word_line_index == [0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2]
+
+
+def test_alignment_token():
+    assert alignment_token("Whoa,") == "whoa"
+    assert alignment_token("o'") == "o'"
+    assert alignment_token("7") == "seven"
+    assert alignment_token("...") == ""
+
+
+def test_alignment_token_no_internal_whitespace():
+    assert alignment_token("21") == "twentyone"
+    assert alignment_token("7th") == "seventh"
+
+
+def test_alignment_token_hyphenated_word():
+    assert alignment_token("well-known") == "wellknown"
+
+
+def test_alignment_token_curly_apostrophe():
+    assert alignment_token("don’t") == "don't"

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

@@ -0,0 +1,336 @@
+import json
+
+import numpy as np
+import pytest
+from songtrace.config import Config
+from songtrace.notes import (
+    MIN_NOTE_SEC, TimedNote, build_notes, hz_to_ultrastar, segment_span,
+    syllabify,
+)
+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
+    times = np.arange(0, duration, 0.01)
+    return times, np.full_like(times, hz), np.full_like(times, 0.9)
+
+
+def assert_no_overlap(notes):
+    for a, b in zip(notes, notes[1:]):
+        assert a.start < b.start
+        assert a.start + a.duration <= b.start
+    assert all(n.duration > 0 for n in notes)
+
+
+def test_hz_to_ultrastar():
+    assert hz_to_ultrastar(261.63) == 0        # C4
+    assert hz_to_ultrastar(440.0) == 9         # A4
+    assert hz_to_ultrastar(220.0) == -3        # A3
+
+
+def test_hz_to_ultrastar_rejects_non_positive():
+    with pytest.raises(ValueError):
+        hz_to_ultrastar(0.0)
+    with pytest.raises(ValueError):
+        hz_to_ultrastar(-100.0)
+
+
+def test_segment_span_single_flat():
+    times, f0, conf = flat_pitch()
+    segs = segment_span(times, f0, conf, 1.0, 2.0)
+    assert len(segs) == 1
+    s, e, midi = segs[0]
+    assert abs(midi - 60.0) < 0.1
+    assert abs(s - 1.0) < 0.02 and abs(e - 2.0) < 0.02
+
+
+def test_segment_span_splits_on_jump():
+    times = np.arange(0, 2.0, 0.01)
+    f0 = np.where(times < 1.0, 261.63, 329.63)   # C4 -> E4
+    conf = np.full_like(times, 0.9)
+    segs = segment_span(times, f0, conf, 0.0, 2.0)
+    assert len(segs) == 2
+    assert abs(segs[0][2] - 60.0) < 0.2 and abs(segs[1][2] - 64.0) < 0.2
+    assert abs(segs[0][1] - segs[1][0]) < 1e-6      # contiguous
+
+
+def test_segment_span_masks_low_conf():
+    times, f0, conf = flat_pitch()
+    conf[:] = 0.1
+    assert segment_span(times, f0, conf, 0.0, 1.0) == []
+
+
+def test_segment_span_ignores_brief_pitch_glitch():
+    times, f0, conf = flat_pitch(duration=1.0)
+    f0[50:52] = 523.25                          # 2-frame octave blip
+    conf = np.full_like(times, 0.9)
+    segs = segment_span(times, f0, conf, 0.0, 1.0)
+    assert len(segs) == 1
+
+
+def test_segment_span_drops_sub_minimum_segments():
+    times, f0, conf = flat_pitch(duration=1.0)
+    assert segment_span(times, f0, conf, 0.5, 0.52) == []
+
+
+def test_syllabify():
+    assert syllabify("reminds", "English") == ["re", "minds"]
+    assert syllabify("a", "English") == ["a"]
+    assert syllabify("xyzzy", None) == ["xyzzy"]
+    assert syllabify("It's", "English") == ["It's"]
+
+
+def test_syllabify_preserves_word_characters():
+    assert "".join(syllabify("well-known", "English")) == "well-known"
+    assert "".join(syllabify("beautiful", "English")) == "beautiful"
+
+
+def test_syllabify_language_without_pyphen_dict_is_not_mishandled_as_english():
+    # Japanese is a known language (e.g. to whisper_client) but has no pyphen
+    # dictionary; it must not silently fall back to English hyphenation rules.
+    assert syllabify("beautiful", "Japanese") == ["beautiful"]
+    assert syllabify("beautiful", "English") == ["beau", "ti", "ful"]
+
+
+def test_build_notes_basic_line():
+    times, f0, conf = flat_pitch()
+    rows = [
+        {"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 == "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
+    assert warnings == []
+
+
+def test_build_notes_melisma_continuation():
+    times = np.arange(0, 3.0, 0.01)
+    f0 = np.where(times < 1.0, 261.63, 329.63)
+    conf = np.full_like(times, 0.9)
+    rows = [{"word": "mine", "start": 0.2, "end": 2.8, "score": 0.9, "line_index": 0}]
+    notes, _, _ = build_notes(rows, times, f0, conf, "English")
+    assert [n.text for n in notes] == ["mine", "~"]
+    assert notes[0].pitch != notes[1].pitch
+
+
+def test_build_notes_unvoiced_word_flagged():
+    times, f0, conf = flat_pitch()
+    conf[:] = 0.0
+    rows = [{"word": "hey", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 0}]
+    notes, _, warnings = build_notes(rows, times, f0, conf, "English")
+    assert notes[0].low_confidence and len(warnings) == 1
+    assert warnings[0] == "1 low-confidence note near 0:01–0:01"
+
+
+def test_build_notes_low_score_word_flagged():
+    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
+
+
+def test_build_notes_unvoiced_word_inherits_previous_pitch():
+    times, f0, conf = flat_pitch(hz=440.0)      # A4 -> 9, not the fallback 0
+    conf[300:] = 0.0
+    rows = [
+        {"word": "one", "start": 1.0, "end": 2.0, "score": 0.9, "line_index": 0},
+        {"word": "two", "start": 4.0, "end": 4.5, "score": 0.9, "line_index": 0},
+    ]
+    notes, _, _ = build_notes(rows, times, f0, conf, "English")
+    assert notes[1].pitch == notes[0].pitch == 9
+    assert notes[1].low_confidence and not notes[0].low_confidence
+
+
+def test_build_notes_unvoiced_first_word_uses_zero_pitch():
+    times, f0, conf = flat_pitch()
+    conf[:] = 0.0
+    rows = [{"word": "hey", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 0}]
+    notes, _, _ = build_notes(rows, times, f0, conf, "English")
+    assert notes[0].pitch == 0
+
+
+def test_build_notes_multisyllable_word_emits_syllables_only():
+    times, f0, conf = flat_pitch()
+    rows = [
+        {"word": "reminds", "start": 1.0, "end": 1.8, "score": 0.9, "line_index": 0},
+        {"word": "reminds", "start": 2.0, "end": 2.8, "score": 0.9, "line_index": 0},
+    ]
+    notes, _, _ = build_notes(rows, times, f0, conf, "English")
+    assert [n.text for n in notes] == ["re", "minds", " re", "minds"]
+
+
+def test_build_notes_more_syllables_than_segments():
+    times, f0, conf = flat_pitch()
+    rows = [{"word": "beautiful", "start": 1.0, "end": 1.9, "score": 0.9,
+             "line_index": 0}]
+    notes, _, _ = build_notes(rows, times, f0, conf, "English")
+    assert [n.text for n in notes] == ["beau", "ti", "ful"]
+    assert all(abs(n.duration - notes[0].duration) < 1e-6 for n in notes)
+    for a, b in zip(notes, notes[1:]):
+        assert abs(a.start + a.duration - b.start) < 1e-6
+
+
+def test_build_notes_subdivides_the_widest_segment_first():
+    times = np.arange(0, 2.0, 0.01)
+    f0 = np.where(times < 1.1, 329.63, 261.63)   # 0.1s E4 then 0.9s C4 in-word
+    conf = np.full_like(times, 0.9)
+    rows = [{"word": "beautiful", "start": 1.0, "end": 2.0, "score": 0.9,
+             "line_index": 0}]
+    notes, _, _ = build_notes(rows, times, f0, conf, "English")
+    assert [n.text for n in notes] == ["beau", "ti", "ful"]
+    assert [n.pitch for n in notes] == [4, 0, 0]      # the 0.9s segment split
+    assert abs(notes[0].duration - 0.1) < 1e-6
+    assert abs(notes[1].duration - notes[2].duration) < 1e-6
+
+
+def test_build_notes_zero_duration_row_gets_minimum_length():
+    times, f0, conf = flat_pitch()
+    rows = [
+        {"word": "...", "start": 1.0, "end": 1.0, "score": 0.0, "line_index": 0},
+        {"word": "go", "start": 1.0, "end": 1.5, "score": 0.9, "line_index": 0},
+    ]
+    notes, _, _ = build_notes(rows, times, f0, conf, "English")
+    assert notes[0].duration >= MIN_NOTE_SEC
+    assert_no_overlap(notes)
+
+
+def test_build_notes_repeated_zero_duration_rows_stay_separate():
+    times, f0, conf = flat_pitch()
+    rows = [{"word": w, "start": 1.0, "end": 1.0, "score": 0.0, "line_index": 0}
+            for w in ("...", "...", "...", "...")]
+    rows.append({"word": "go", "start": 1.0, "end": 1.5, "score": 0.9,
+                 "line_index": 0})
+    notes, _, _ = build_notes(rows, times, f0, conf, "English")
+    assert len(notes) == 5
+    assert_no_overlap(notes)
+
+
+def test_build_notes_short_multisyllable_word_does_not_overlap():
+    times, f0, conf = flat_pitch()
+    rows = [
+        {"word": "reminds", "start": 8.92, "end": 8.99, "score": 0.9,
+         "line_index": 0},
+        {"word": "me", "start": 8.99, "end": 9.20, "score": 0.9, "line_index": 0},
+    ]
+    notes, _, _ = build_notes(rows, times, f0, conf, "English")
+    assert [n.text for n in notes] == ["re", "minds", " me"]
+    assert_no_overlap(notes)
+
+
+def test_build_notes_never_overlaps_on_dense_input():
+    rng = np.random.default_rng(11)
+    times = np.arange(0, 40.0, 0.01)
+    words = ["We", "count", "a", "beautiful", "number", "reminds", "us",
+             "everything", "we", "listed", "yesterday", "oh"]
+    for _ in range(8):
+        f0 = 220.0 * 2 ** (rng.integers(0, 12, len(times)) // 3 / 12.0)
+        conf = np.where(rng.random(len(times)) < 0.9, 0.9, 0.1)
+        rows, t = [], 0.5
+        for i in range(80):
+            dur = float(rng.uniform(0.06, 0.55))
+            rows.append({"word": words[i % len(words)], "start": t,
+                         "end": t + dur, "score": 0.9, "line_index": i // 6})
+            t += dur + float(rng.uniform(0.0, 0.15))
+        notes, _, _ = build_notes(rows, times, f0, conf, "English")
+        assert_no_overlap(notes)
+
+
+def test_build_notes_starts_are_non_decreasing():
+    times = np.arange(0, 12.0, 0.01)
+    f0 = 220.0 * 2 ** (np.floor(times * 2) % 5 / 12.0)   # stepped melody
+    conf = np.where((times % 3.0) < 2.6, 0.9, 0.1)       # unvoiced gaps
+    words = ["We", "count", "a", "beautiful", "number", "that",
+             "reminds", "us", "of", "everything", "we", "list"]
+    rows = []
+    for i, w in enumerate(words):
+        dur = 0.8 if i % 3 else 0.07       # every third word sung very fast
+        rows.append({"word": w, "start": 0.5 + i * 0.9, "end": 0.5 + i * 0.9 + dur,
+                     "score": 0.9 if i % 5 else 0.2, "line_index": i // 4})
+    notes, breaks, warnings = build_notes(rows, times, f0, conf, "English")
+    assert len(notes) >= len(words)
+    starts = [n.start for n in notes]
+    assert starts == sorted(starts)
+    assert breaks == sorted(breaks) and len(breaks) == 2
+    assert_no_overlap(notes)
+    assert warnings and all("low-confidence note" in w for w in warnings)
+
+
+def test_build_notes_line_initial_after_break_has_no_space():
+    times, f0, conf = flat_pitch()
+    rows = [
+        {"word": "one", "start": 1.0, "end": 1.4, "score": 0.9, "line_index": 0},
+        {"word": "two", "start": 2.0, "end": 2.4, "score": 0.9, "line_index": 1},
+        {"word": "three", "start": 3.0, "end": 3.4, "score": 0.9, "line_index": 1},
+    ]
+    notes, breaks, _ = build_notes(rows, times, f0, conf, "English")
+    assert [n.text for n in notes] == ["one", "two", " three"]
+    assert breaks == [1.7]
+
+
+def test_notes_stage_writes_json(tmp_path):
+    work = tmp_path / "w"
+    work.mkdir()
+    times, f0, conf = flat_pitch()
+    np.savez(work / "pitch.npz", times=times, f0=f0, conf=conf)
+    (work / "alignment.json").write_text(json.dumps([
+        {"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"),
+              cfg=Config(whisper_url="u"), work=work, log=lambda m: None)
+    stage = notes_stage_mod.notes_stage()
+    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"]] == ["It's", "gone"]
+    assert data["breaks"] == [2.25]
+    assert data["warnings"] == []
+    assert TimedNote(**data["notes"][0]).pitch == 0
+
+
+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

tests/test_package.py

@@ -0,0 +1,205 @@
+import json
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+from songtrace.config import Config
+from songtrace.pipeline import (
+    STAGE_ORDER, Ctx, PipelineError, SongInput, run_pipeline, song_slug,
+)
+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")
+
+
+def make_ctx(tmp_path, cover=None):
+    work = tmp_path / "work"
+    work.mkdir()
+    (work / "song.txt").write_text(SONG_TXT)
+    (work / "audio.wav").write_bytes(b"w")
+    (work / "source_video.webm").write_bytes(b"v")
+    (work / "meta.json").write_text(json.dumps(
+        {"video_file": "source_video.webm", "thumbnail": None}))
+    inp = SongInput(title="T", artist="A", lyrics_text="x", cover_path=cover)
+    cfg = Config(whisper_url="u", output_dir=tmp_path / "out", work_dir=tmp_path)
+    return Ctx(inp=inp, cfg=cfg, work=work, log=lambda m: None)
+
+
+def make_cover(tmp_path):
+    p = tmp_path / "c.png"
+    Image.new("RGB", (640, 480), "red").save(p)
+    return p
+
+
+def make_pipeline_inputs(tmp_path, cover=None):
+    """Set up inputs at the exact work-dir path run_pipeline() would use."""
+    cfg = Config(whisper_url="u", output_dir=tmp_path / "out",
+                 work_dir=tmp_path / "work_root")
+    inp = SongInput(title="T", artist="A", lyrics_text="x", cover_path=cover)
+    work = cfg.work_dir / song_slug(inp)
+    work.mkdir(parents=True)
+    (work / "song.txt").write_text(SONG_TXT)
+    (work / "audio.wav").write_bytes(b"w")
+    (work / "source_video.webm").write_bytes(b"v")
+    (work / "meta.json").write_text(json.dumps(
+        {"video_file": "source_video.webm", "thumbnail": None}))
+    return inp, cfg
+
+
+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").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"))
+    ctx = make_ctx(tmp_path, cover=make_cover(tmp_path))
+    package.package_stage().run(ctx)
+    out = tmp_path / "out" / "A - T"
+    song = parse_ultrastar((out / "A - T.txt").read_text())
+    assert get_header(song, "VIDEO") == "A - T.mp4"
+    # VIDEO keeps its original slot, ahead of BPM/GAP
+    keys = [k for k, _ in song.headers]
+    assert keys.index("VIDEO") < keys.index("BPM") < keys.index("GAP")
+
+
+def test_package_no_cover_drops_header(tmp_path, monkeypatch):
+    monkeypatch.setattr(package, "ffmpeg", lambda *a: Path(a[-1]).write_bytes(b"m"))
+    monkeypatch.setattr(package, "ffprobe_codec", lambda p: ("webm", "vp9"))
+    ctx = make_ctx(tmp_path, cover=None)
+    package.package_stage().run(ctx)
+    song = parse_ultrastar((tmp_path / "out" / "A - T" / "A - T.txt").read_text())
+    assert get_header(song, "COVER") is None
+
+
+def test_package_uses_work_thumbnail_when_no_cover_path(tmp_path, monkeypatch):
+    monkeypatch.setattr(package, "ffmpeg", lambda *a: Path(a[-1]).write_bytes(b"m"))
+    monkeypatch.setattr(package, "ffprobe_codec", lambda p: ("webm", "vp9"))
+    ctx = make_ctx(tmp_path, cover=None)
+    make_cover(tmp_path).rename(ctx.work / "thumb.png")
+    meta = json.loads((ctx.work / "meta.json").read_text())
+    meta["thumbnail"] = "thumb.png"
+    (ctx.work / "meta.json").write_text(json.dumps(meta))
+    package.package_stage().run(ctx)
+    out = tmp_path / "out" / "A - T"
+    assert (out / "A - T.jpg").exists()
+    song = parse_ultrastar((out / "A - T.txt").read_text())
+    assert get_header(song, "COVER") == "A - T.jpg"
+
+
+def test_package_outputs_done_marker():
+    ctx_outputs = package.package_stage().outputs
+    cfg = Config(whisper_url="u", output_dir=Path("out"), work_dir=Path("work"))
+    inp = SongInput(title="T", artist="A", lyrics_text="x")
+    ctx = Ctx(inp=inp, cfg=cfg, work=Path("work"), log=lambda m: None)
+    assert ctx_outputs(ctx) == [Path("work/package.done")]
+
+
+def test_package_corrupt_cover_degrades_to_no_cover(tmp_path, monkeypatch):
+    monkeypatch.setattr(package, "ffmpeg", lambda *a: Path(a[-1]).write_bytes(b"m"))
+    monkeypatch.setattr(package, "ffprobe_codec", lambda p: ("webm", "vp9"))
+    bad_cover = tmp_path / "bad.jpg"
+    bad_cover.write_bytes(b"not an image")
+    ctx = make_ctx(tmp_path, cover=bad_cover)
+    package.package_stage().run(ctx)
+    out = tmp_path / "out" / "A - T"
+    assert not (out / "A - T.jpg").exists()
+    song = parse_ultrastar((out / "A - T.txt").read_text())
+    assert get_header(song, "COVER") is None
+
+
+def test_package_partial_failure_is_not_cached(tmp_path, monkeypatch):
+    monkeypatch.setattr(package, "ffmpeg", lambda *a: Path(a[-1]).write_bytes(b"m"))
+
+    def boom(p):
+        raise PipelineError("ffprobe failed")
+
+    monkeypatch.setattr(package, "ffprobe_codec", boom)
+    ctx = make_ctx(tmp_path, cover=make_cover(tmp_path))
+    with pytest.raises(PipelineError):
+        package.package_stage().run(ctx)
+    out = tmp_path / "out" / "A - T"
+    assert (out / "A - T.txt").exists()
+    assert (out / "A - T.mp3").exists()
+    assert not (out / "A - T.webm").exists()
+    assert not package.package_stage().outputs(ctx)[0].exists()
+
+
+def test_package_success_is_cached_by_pipeline(tmp_path, monkeypatch):
+    monkeypatch.setattr(package, "ffmpeg", lambda *a: Path(a[-1]).write_bytes(b"m"))
+    monkeypatch.setattr(package, "ffprobe_codec", lambda p: ("webm", "vp9"))
+    inp, cfg = make_pipeline_inputs(tmp_path, cover=make_cover(tmp_path))
+    stage = package.package_stage()
+    run_pipeline(inp, cfg, log=lambda m: None, stages=[stage])
+    logs = []
+    run_pipeline(inp, cfg, log=logs.append, stages=[stage])
+    assert any("[package] cached, skipping" in m for m in logs)
+
+
+def test_package_retry_after_partial_failure_completes_folder(tmp_path, monkeypatch):
+    calls = {"n": 0}
+
+    def flaky_ffprobe(p):
+        calls["n"] += 1
+        if calls["n"] == 1:
+            raise PipelineError("ffprobe failed")
+        return ("webm", "vp9")
+
+    monkeypatch.setattr(package, "ffmpeg", lambda *a: Path(a[-1]).write_bytes(b"m"))
+    monkeypatch.setattr(package, "ffprobe_codec", flaky_ffprobe)
+    inp, cfg = make_pipeline_inputs(tmp_path, cover=make_cover(tmp_path))
+    stage = package.package_stage()
+    with pytest.raises(PipelineError):
+        run_pipeline(inp, cfg, log=lambda m: None, stages=[stage])
+    out = cfg.output_dir / "A - T"
+    assert (out / "A - T.txt").exists() and (out / "A - T.mp3").exists()
+    assert not (out / "A - T.webm").exists()
+
+    run_pipeline(inp, cfg, log=lambda m: None, stages=[stage])
+    assert (out / "A - T.webm").exists()
+    assert (out / "A - T.jpg").exists()
+
+
+def test_slash_in_title_is_stripped_from_folder_and_filenames(tmp_path, monkeypatch):
+    monkeypatch.setattr(package, "ffmpeg", lambda *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))
+    ctx.inp.title = "T/2"
+    package.package_stage().run(ctx)
+    out = tmp_path / "out" / "A - T2"
+    assert (out / "A - T2.txt").exists()
+    assert (out / "A - T2.mp3").exists()
+
+
+def test_all_stages_matches_stage_order():
+    assert [s.name for s in all_stages()] == STAGE_ORDER

tests/test_pipeline.py

@@ -0,0 +1,101 @@
+import json
+from pathlib import Path
+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",
+                  work_dir=tmp_path / "work")
+
+def make_inp():
+    return SongInput(title="T/est", artist="A", lyrics_text="la la")
+
+def fake_stage(name, calls):
+    def outputs(ctx):
+        return [ctx.work / f"{name}.done"]
+    def run(ctx):
+        calls.append(name)
+        (ctx.work / f"{name}.done").write_text("x")
+    return Stage(name=name, outputs=outputs, run=run)
+
+def test_slug_strips_slash():
+    assert song_slug(make_inp()) == "A - Test"
+
+def test_runs_all_stages_then_skips_cached(tmp_path):
+    cfg, inp, calls = make_cfg(tmp_path), make_inp(), []
+    stages = [fake_stage("s1", calls), fake_stage("s2", calls)]
+    run_pipeline(inp, cfg, log=lambda m: None, stages=stages)
+    assert calls == ["s1", "s2"]
+    run_pipeline(inp, cfg, log=lambda m: None, stages=stages)
+    assert calls == ["s1", "s2"]
+
+def test_force_from_reruns_tail(tmp_path):
+    cfg, inp, calls = make_cfg(tmp_path), make_inp(), []
+    stages = [fake_stage("s1", calls), fake_stage("s2", calls), fake_stage("s3", calls)]
+    run_pipeline(inp, cfg, log=lambda m: None, stages=stages)
+    calls.clear()
+    run_pipeline(inp, cfg, log=lambda m: None, stages=stages, force_from="s2")
+    assert calls == ["s2", "s3"]
+
+def test_warnings_surfaced(tmp_path):
+    cfg, inp = make_cfg(tmp_path), make_inp()
+    def run(ctx):
+        (ctx.work / "notes_sec.json").write_text(
+            json.dumps({"notes": [], "breaks": [], "warnings": ["w1"]}))
+        (ctx.work / "n.done").write_text("x")
+    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

@@ -0,0 +1,37 @@
+import numpy as np
+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):
+    work = tmp_path / "w"
+    work.mkdir()
+    times = np.arange(0, 1.0, 0.01)
+    f0 = np.full_like(times, 220.0)
+    conf = np.full_like(times, 0.9)
+    monkeypatch.setattr(pitch, "track_pitch", lambda p, m, d: (times, f0, conf))
+    ctx = Ctx(inp=SongInput(title="T", artist="A", lyrics_text="x"),
+              cfg=Config(whisper_url="u"), work=work, log=lambda m: None)
+    pitch.pitch_stage().run(ctx)
+    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

@@ -0,0 +1,137 @@
+import dataclasses
+from pathlib import Path
+
+import pytest
+
+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)
+
+
+def song(**kw):
+    base = dict(title="T", artist="A", lyrics_text="la", youtube_url="http://y")
+    return SongInput(**{**base, **kw})
+
+
+def cfg_for(tmp_path):
+    return Config(whisper_url="u", work_dir=tmp_path / "work",
+                  output_dir=tmp_path / "out")
+
+
+def test_every_song_input_field_is_mapped():
+    """A field added to SongInput without a FIELD_STAGE entry would make edits to
+    it invalidate nothing, silently building from stale intermediates."""
+    actual = {f.name for f in dataclasses.fields(SongInput)}
+    assert actual - set(FIELD_STAGE) == set()
+    assert set(FIELD_STAGE) - actual == set()
+
+
+def test_every_mapped_stage_is_a_real_stage():
+    assert set(FIELD_STAGE.values()) <= set(STAGE_ORDER)
+
+
+def test_no_change_means_no_force_from():
+    assert plan(song(), song()) is None
+
+
+@pytest.mark.parametrize("field,value,stage", [
+    ("youtube_url", "http://other", "acquire"),
+    ("video_path", Path("/tmp/v.mp4"), "acquire"),
+    ("language", "de", "transcribe"),
+    ("lyrics_text", "different words", "align"),
+    ("title", "Other", "grid"),
+    ("artist", "Other", "grid"),
+    ("genre", "rock", "grid"),
+    ("year", 1999, "grid"),
+    ("bpm_override", 123.0, "grid"),
+    ("cover_path", Path("/tmp/c.jpg"), "package"),
+])
+def test_single_field_maps_to_its_stage(field, value, stage):
+    assert plan(song(), song(**{field: value})) == stage
+
+
+def test_earliest_stage_wins_when_several_change():
+    new = song(lyrics_text="different", year=1999, language="de")
+    assert plan(song(), new) == "transcribe"
+
+
+def test_changed_fields_lists_what_moved():
+    assert sorted(changed_fields(song(), song(year=1999, genre="rock"))) == \
+        ["genre", "year"]
+
+
+def test_slug_fields_invalidate_no_later_than_the_stage_that_writes_the_slug():
+    """song.txt embeds the slug in #MP3/#COVER/#VIDEO and is written by `grid`,
+    so a title/artist edit must rerun grid or earlier for relocate_work to be safe."""
+    for field in ("title", "artist"):
+        assert STAGE_ORDER.index(FIELD_STAGE[field]) <= STAGE_ORDER.index("grid")
+
+
+def test_relocate_moves_the_work_dir_when_the_slug_changes(tmp_path):
+    cfg = cfg_for(tmp_path)
+    src = cfg.work_dir / "A - T"
+    src.mkdir(parents=True)
+    (src / "audio.wav").write_bytes(b"x")
+    assert relocate_work(song(), song(title="Fixed"), cfg) is True
+    assert not src.exists()
+    assert (cfg.work_dir / "A - Fixed" / "audio.wav").read_bytes() == b"x"
+
+
+def test_relocate_is_a_noop_when_the_slug_is_unchanged(tmp_path):
+    cfg = cfg_for(tmp_path)
+    src = cfg.work_dir / "A - T"
+    src.mkdir(parents=True)
+    assert relocate_work(song(), song(year=1999), cfg) is False
+    assert src.exists()
+
+
+def test_relocate_is_a_noop_when_there_is_nothing_to_move(tmp_path):
+    cfg = cfg_for(tmp_path)
+    assert relocate_work(song(), song(title="Fixed"), cfg) is False
+
+
+def test_relocate_refuses_to_clobber_an_existing_work_dir(tmp_path):
+    cfg = cfg_for(tmp_path)
+    (cfg.work_dir / "A - T").mkdir(parents=True)
+    (cfg.work_dir / "A - Fixed").mkdir(parents=True)
+    with pytest.raises(PipelineError, match="already exists"):
+        relocate_work(song(), song(title="Fixed"), cfg)
+    assert (cfg.work_dir / "A - T").exists()
+
+
+def test_superseded_output_names_the_replaced_folder(tmp_path):
+    root = tmp_path / "out"
+    assert superseded_output(str(root / "A - Old"), str(root / "A - New"), root) == \
+        (root / "A - Old").resolve()
+
+
+def test_superseded_output_is_none_when_the_slug_did_not_change(tmp_path):
+    root = tmp_path / "out"
+    assert superseded_output(str(root / "A - T"), str(root / "A - T"), root) is None
+
+
+def test_superseded_output_is_none_without_a_previous_build(tmp_path):
+    root = tmp_path / "out"
+    assert superseded_output(None, str(root / "A - T"), root) is None
+
+
+def test_superseded_output_refuses_a_path_outside_the_output_root(tmp_path):
+    root = tmp_path / "out"
+    assert superseded_output(str(tmp_path / "elsewhere"), str(root / "A - T"), root) is None
+
+
+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

@@ -0,0 +1,26 @@
+import numpy as np
+import soundfile as sf
+import torch
+from songtrace.config import Config
+from songtrace.pipeline import Ctx, SongInput
+from songtrace.stages import separate
+
+
+def test_separate_writes_stems(tmp_path, monkeypatch):
+    work = tmp_path / "w"
+    work.mkdir()
+    (work / "audio.wav").write_bytes(b"")
+    stems = {
+        "vocals": torch.ones(2, 100) * 0.5,
+        "drums": torch.ones(2, 100) * 0.1,
+        "bass": torch.ones(2, 100) * 0.1,
+        "other": torch.ones(2, 100) * 0.1,
+    }
+    monkeypatch.setattr(separate, "separate_audio", lambda p, m, d: stems)
+    ctx = Ctx(inp=SongInput(title="T", artist="A", lyrics_text="x"),
+              cfg=Config(whisper_url="u"), work=work, log=lambda m: None)
+    separate.separate_stage().run(ctx)
+    vocals, sr = sf.read(work / "vocals.wav")
+    assert sr == 44100 and vocals.shape == (100, 2)
+    instrumental, _ = sf.read(work / "instrumental.wav")
+    assert np.allclose(instrumental, 0.3, atol=1e-4)

tests/test_transcribe.py

@@ -0,0 +1,95 @@
+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)
+
+def test_vocal_sections_merges_close_segments():
+    sections = vocal_sections([seg(2, 5), seg(6, 9), seg(30, 33)])
+    assert sections == [(1.0, 10.0), (29.0, 34.0)]
+
+def test_vocal_sections_handles_out_of_order_segments():
+    sections = vocal_sections([seg(30, 33), seg(1, 4)])
+    assert sections == [(0.0, 5.0), (29.0, 34.0)]
+
+def test_vocal_sections_keeps_contained_segment():
+    sections = vocal_sections([seg(1, 10), seg(3, 5)])
+    assert sections == [(0.0, 11.0)]
+
+def test_similarity_high_for_matching_lyrics():
+    ref = normalize_lyrics("it's one two three\nfour five six seven eight")
+    segs = [seg(0, 2, "It's one two three"), seg(2, 4, "four five six seven eight")]
+    assert lyrics_similarity(segs, ref) > 0.9
+
+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

@@ -0,0 +1,38 @@
+from pathlib import Path
+from songtrace.ultrastar import (
+    Note, LineBreak, parse_ultrastar, serialize_ultrastar,
+    get_header, format_bpm, parse_bpm,
+)
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+def load(name):
+    return (FIXTURES / name).read_text(encoding="utf-8", errors="replace")
+
+def test_parse_headers_and_notes():
+    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")
+    assert any(isinstance(x, LineBreak) and x.beat == 95 for x in song.body)
+    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("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("chart_latin1.txt"))
+    assert any(n.pitch == -9 for n in song.body if isinstance(n, Note))
+
+def test_round_trip():
+    for name in ("chart_latin1.txt", "chart_crlf.txt"):
+        song = parse_ultrastar(load(name))
+        again = parse_ultrastar(serialize_ultrastar(song))
+        assert again == song
+
+def test_format_bpm():
+    assert format_bpm(256.0) == "256"
+    assert format_bpm(217.98) == "217,98"

tests/test_whisper.py

@@ -0,0 +1,60 @@
+import httpx
+from pathlib import Path
+from songtrace.config import Config
+from songtrace.whisper_client import TranscriptSegment, transcribe
+
+def test_transcribe_parses_segments(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["auth"] = request.headers.get("authorization")
+        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/v1", whisper_api_key="sekrit")
+    segs = transcribe(cfg, audio, client=client)
+    assert segs == [TranscriptSegment(start=0.5, end=2.0, text="hello world")]
+    assert seen["url"] == "http://w:9000/v1/audio/transcriptions"
+    assert seen["auth"] == "Bearer sekrit"
+
+
+def test_transcribe_maps_language_to_iso_code(tmp_path):
+    audio = tmp_path / "v.wav"
+    audio.write_bytes(b"RIFF")
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["body"] = request.read().decode("utf-8", errors="replace")
+        return httpx.Response(200, json={"segments": []})
+
+    client = httpx.Client(transport=httpx.MockTransport(handler))
+    cfg = Config(whisper_url="http://w:9000/v1")
+    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)