USTX file format

USTX is the project file format for OpenUtau. This document outlines the structure and semantics of the USTX format for developers building tools that process USTX files.

Basic concepts

• Tick: the time unit in midi. 1 quarter note equals to 480 ticks.
• Midi number: tone representation in midi. C4 = 60. Unit is semitone

File Structure

A USTX file is a YAML-based (YAML 1.2) text format in UTF-8 encoding, with the following top-level sections:

UProject

Field	Type	Description
name	string	Project name
ustx_version	string	USTX format version, currently 0.6
resolution	int	Ticks per quarter note, always 480
key	int	Musical key of the project, used for scale degree displaying. 0 means C major or A minor
time_signature	list	List of time signature changes
tempos	list	List of tempo changes
tracks	list	List of tracks
voice_parts	list	List of voice parts (part containing notes for synthesis)
wave_parts	list	List of wave parts (external audio file, usually instrumental of the song)

bpm, beat_per_bar and beat_unit under the project root are deprecated. To get the tempo and time signatures, please use tempos and time_signature.

Expressions

Defines vocal parameters (e.g., dynamics, vibrato) as curves or numerical values.
Located under expressions as key-value pairs. Each expression has:

Field	Type	Description
name	string	Human-readable name (e.g., "dynamics (curve)")
abbr	string	Short identifier (e.g., "dyn")
type	string	Curve, Options, or Numerical
min/max	int	Value range
default_value	int	Default if not explicitly set
is_flag	bool	Whether the parameter is a UTAU resampler flag
flag	string	UTAU resampler flag symbol (e.g., "g" for gender)
options	list	For Options type: list of possible values (e.g., ["off", "on"])

Example:

dyn:
  name: dynamics (curve)
  abbr: dyn
  type: Curve
  min: -240
  max: 120
  default_value: 0

Time and Tempo

• Time Signatures (time_signatures):
  Defines changes in time signature. Each entry includes:

  • bar_position: Bar number where the change applies.
  • beat_per_bar: Numerator (e.g., 4 for 4/4).
  • beat_unit: Denominator (e.g., 4 for 4/4).

• Tempos (tempos):
  Defines BPM changes. Each entry includes:

  • position: Tick position where the tempo change occurs.
  • bpm: BPM value.

Tracks

Defines audio tracks under tracks. Each track includes:

Field	Type	Description
singer	string	Voicebank identifier
phonemizer	string	Phonemizer plugin
track_name	string	Track label
track_color	string	Display color (e.g., "Blue")
mute/solo	bool	Mute/solo state
volume	float	Track volume (dB)
voice_color_names	list	List of available voice colors in the voicebank

Voice Parts

Contains musical notes and phrases under voice_parts. Each part includes:

Field	Type	Description
duration	int	Total duration in ticks
name	string	Name of the part
track_no	int	Index of the track that the part belongs to
position	int	Starting tick position relative to the project
notes	list	List of notes (see below)
curves	list	Curve expressions (see below)

Note

Each note under notes has:

Field	Type	Description
position	int	Start tick relative to the starting position voice part
duration	int	Note length in ticks
tone	int	MIDI note number (e.g., 60 = C4)
lyric	string	Lyric text (e.g., "san")
pitch	object	Pitch control points
vibrato	object	Vibrato parameters (depth, period, fade-in/out)
phoneme_expressions	list	Numerical and option expressions edited per phoneme by the user
phoneme_overrides	list	Phoneme name and position (tick offset relative to the original phonemizer result) edited by the user

Example:

  - position: 1920
    duration: 720
    tone: 70
    lyric: san
    pitch:
      data:
      - {x: -274.03845, y: 0, shape: io}
      - {x: -158.65384, y: -32.46212, shape: io}
      - {x: 40, y: 0, shape: io}
      snap_first: true
    vibrato: {length: 0, period: 175, depth: 25, in: 10, out: 10, shift: 0, drift: 0, vol_link: 0}
    phoneme_expressions:
    - {index: 0, abbr: clr, value: 1}
    - {index: 1, abbr: clr, value: 2}
    phoneme_overrides:
    - index: 1
      phoneme: a
    - index: 0
      offset: 65

Curves

Defines automation curves (e.g., pitch, dynamics) under curves.

Field	Type	Description
xs	List	Tick position of each sample point in the curve
ys	List	Value at each sample point
abbr	string	Expression abbr

Wave Parts

External audio files imported to the project, under wave_parts

Field	Type	Description
name	string	Name of the part
track_no	int	Index of the track that the part belongs to
position	int	Starting tick position relative to the project
relative_path	string	Path to the audio file relative to the .ustx file, absolute path if on another drive
file_duration_ms	float	Duration of the audio file in milliseconds

Developer notes

For python developers, please use ruamel.yaml when working with .ustx files, because it supports yaml 1.2 . Don't use pyyaml.

References

The reading and writing of USTX files is officially implemented in OpenUtau.Core/Ustx

Below are third-party implementations of USTX reading and writing:

• Libresvip, in python