OpenUTAU CLI

[christianazinn]

Implements command-line rendering for OpenUTAU.

This PR adds a headless render command to the existing OpenUtau executable so projects can be rendered from scripts without opening the GUI. It currently supports rendering one project to one WAV, or rendering all files in a folder to an output folder in batch processing (this is not parallelized - more on this below). Related: Discord #ideas post, #1615

Since this is a somewhat new direction for OpenUTAU and will likely need to be added to the docs, I've done my best to provide as much detail as possible in this PR description.

Motivation

OpenUTAU provides an implementation for rendering vocal synths with a variety of backends, but it's only usable through a graphical interface. This makes it difficult to render files en masse for any reason, such as for DiffSinger "gacha rendering," where by leveraging the stochastic nature of the acoustic model, one can repeatedly render a segment until the tuning sounds right. Other uses include scripting renders, data generation, and automated regression workflows.

Usage

Single project:

OpenUtau.exe render --input path/to/song.ustx --output path/to/song.wav

Batch folder render:

OpenUtau.exe render `
  --input path/to/projects `
  --output path/to/renders `
  --singer "Singer Name" `
  --renderer WORLDLINE-R

When --input is a directory, files inside that directory are rendered serially to matching .wav files in the output directory. Supported project extensions in directory mode are the same as in the GUI (it dispatches to the same Formats.LoadProject under the hood).

Note that this doesn't scan subdirectories. It also runs serially because it seems like concurrency is messy, which means it doesn't provide as much runtime benefit as I would like, although this should still provide better performance than individual CLI invocations because you skip the setup/teardown cost of the headless host (more on this below). I'd like to look into parallelizing this in a later PR.

With overrides, e.g. to change the voicebank:

OpenUtau.exe render `
  --input path/to/song.ust `
  --output path/to/song.wav `
  --singer "Singer Name" `
  --renderer WORLDLINE-R `
  --phonemizer "JA VCV"

Supported override options:

• --singer <id-or-name>
• --renderer <CLASSIC|WORLDLINE-R|WORLDLINE-R2|ENUNU|VOGEN|DIFFSINGER|VOICEVOX>
• --phonemizer <name-or-type>
• --resampler <name>
• --wavtool <name>
• --singers-path <path>
• --onnx-runner <CPU|DirectML|CoreML|NNAPI>
• --onnx-gpu <device-index>
• --diffsinger-depth <value>
• --diffsinger-steps <count>
• --diffsinger-variance-steps <count>
• --diffsinger-pitch-steps <count>
• --diffsinger-tensor-cache <true|false>

If no override is provided, rendering uses the project’s saved settings and the same fallback behavior as GUI project loading/validation.

These overrides are applied to the whole project, i.e. every track gets the same override. Per-track shenanigans seem too complicated to implement for now, and I personally use different USTs for each vocal track, so I'm not too inclined to bother.

Implementation details

Conveniently, the basic tools we need to do programmatic rendering already exist, in the form of Formats.LoadProject to load a project file and PlaybackManager.RenderMixdown to render it to WAV. Surely, then, it's just a matter of piping one into the other and setting overrides, right? Wrong! RenderMixdown assumes there exist a bunch of utilities and managers that are started by the Avalonia app launch path. Therefore, we need to somehow launch these, or else risk running into weird problems like voicebanks not loading properly, as in this previous attempt at a CLI.

Therefore, we need to do some scaffolding. This is accomplished in the HeadlessOpenUtauHost which essentially handles the CLI context and thus allows us to implement the simple load-then-render approach. This rendering is handled through a HeadlessRenderCommand and routed to individual HeadlessRenderer.RenderOneAsync calls to render each individual project file. Details below:

Brief overview of roles of new classes

• HeadlessOpenUtauHost

  • initializes ToolsManager, SingerManager, and DocManager
  • creates a non-UI scheduler and synchronization context
  • provides a safe PostOnUIThread replacement for command dispatch
  • captures progress and error notifications for CLI output

• HeadlessRenderer.RenderOneAsync

  • loads projects through Formats.ReadProject
  • applies optional singer/renderer/phonemizer/tool overrides
  • validates the project
  • waits for phonemizer work to finish
  • renders through the existing PlaybackManager.RenderMixdown
  • checks that the output WAV was actually written and contains audio data

• HeadlessRenderCommand

  • parses command-line options
  • expands single-file or directory input into RenderJob instances
  • runs jobs under one HeadlessOpenUtauHost
  • reports per-file failures in batch mode and returns a nonzero exit code if any item fails

The CLI is routed from OpenUtau/Program.cs before Avalonia startup, and the normal GUI startup path is unchanged for all other invocations, so apart from some small changes to the PhonemizerRunner, this should not affect the GUI app at all. Speaking of which...

Phonemization

Project validation can enqueue asynchronous phonemizer work, and for headless rendering, we need to make sure we await on all phonemizer responses before starting mixdown. To do this, we add a narrow idle-wait API to PhonemizerRunner, in the form of Task WaitForIdleAsync(), and we also track the idle waiters on each queued request, which are completed only after the main scheduler runs the response application task. This path shouldn't be touched by the GUI app at all, with the exception of a few functions that have been updated to accept the new API, which should be backward-compatible.

Override behavior

CLI overrides apply to every track in the project, and in batch mode, every track in every project. Maybe later we can address tracks individually, or individual projects within a folder, but I feel that is outside the scope of this PR.

Please let me know if I have missed any pertinent config options to pass through to any of the backends.

Phonemizer resolution accepts:

• saved full type name
• display name
• tag, such as JA VCV or DIFFS JA
• class name

Renderer names are validated before rendering. If the renderer exists but does not support the selected singer type, rendering fails with a clear error such as:

Renderer DIFFSINGER is not supported for singer <name>.

Batch rendering

Continued from the bottom of "Usage," batch mode reuses one headless host for all files in the command. which avoids repeating manager/plugin/singer/tool initialization for each render. However, since the existing render path uses process-wide manager, scheduler, cache, and notification state, I don't think it's safe to try rendering multiple projects concurrently in this PR. The internal renderer may still use its own existing parallelism. (To be looked into in a future PR?)

If one file fails in batch mode, the command reports the error, continues with the remaining files, and exits with code 1 at the end.

Exit codes

• 0: render completed successfully
• 1: render failed, or at least one batch item failed
• 2: invalid command-line usage

Testing

I added a suite of CLI tests for what I thought was pretty comprehensive, including:

• CLI command detection and option parsing
• invalid argument handling
• single-file and directory render-plan expansion
• batch extension filtering and duplicate output detection
• phonemizer resolution by type/name/tag/class name
• renderer resolution and unsupported renderer/singer combinations
• project readiness failures for missing singers, missing renderers, and missing render phrases

I've also tested it locally on my Windows machine in both single-file and batch modes, but only on UTAU; I have not yet tried DiffSinger or ENUNU.

[Copilot]

Pull request overview

This PR adds a headless CLI entry point (render) to the existing OpenUtau executable, enabling scripted/batch project rendering to WAV without launching the GUI. It introduces a headless host to initialize the normally-UI-owned managers/scheduler and adds a phonemizer “idle wait” API so phonemization can complete before mixdown rendering.

Changes:

• Add a render command routed from OpenUtau/Program.cs to run headlessly (including console attach on Windows).
• Introduce OpenUtau.Core.Headless components (HeadlessOpenUtauHost, HeadlessRenderCommand, HeadlessRenderer, scheduler/sync context, job/options models).
• Extend PhonemizerRunner with WaitForIdleAsync() to support awaiting phonemization completion in headless rendering, plus add CLI-focused tests.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
OpenUtau/Program.cs	Routes render invocations into headless execution path before Avalonia startup; adds console attach + NetMQ cleanup refactor.
OpenUtau.Test/Core/Headless/HeadlessRenderCommandTest.cs	Adds tests for CLI detection/parsing, render plan expansion, and override resolution/validation helpers.
OpenUtau.Core/Properties/AssemblyInfo.cs	Exposes internals to the test assembly for headless/CLI testing.
OpenUtau.Core/Headless/RenderJob.cs	Adds CLI job + options models for rendering and preference overrides.
OpenUtau.Core/Headless/HeadlessTaskScheduler.cs	Provides a single-threaded task scheduler + sync context to emulate UI-thread dispatch headlessly.
OpenUtau.Core/Headless/HeadlessRenderException.cs	Adds a dedicated exception type for headless rendering errors.
OpenUtau.Core/Headless/HeadlessRenderer.cs	Implements load/override/validate/await-phonemize/render mixdown flow for one project.
OpenUtau.Core/Headless/HeadlessRenderCommand.cs	Implements render command parsing, batch planning, and serial execution with exit codes.
OpenUtau.Core/Headless/HeadlessOpenUtauHost.cs	Initializes required managers/scheduler/subscriptions for headless rendering and captures errors/progress.
OpenUtau.Core/Api/PhonemizerRunner.cs	Adds WaitForIdleAsync() and request accounting so headless rendering can await phonemizer completion reliably.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.