pyutau 1.0.0

A python library/module for parsing UTAU plugin data

pyUtau

A complete bodge of a Python library made by UtaUtaUtau. Interprets data that UTAU sends through plugins. Made to work for UST Version 1.20 only. I am not an avid programmer, please don't expect much...

To use, it's just one file. Clone or download this repo, and put pyutau.py somewhere in your project. Import it with none other than import pyutau

To use, you can now install this as a Python package through pip by using:

pip install git+https://github.com/UtaUtaUtau/pyUtau

You can still get the pyutau.py file from the folders but I recommend doing this instead.

All information used to make this plugin is from this @wiki page and this C# library. I just translated everything through DeepL to understand how these work.

I'll just put the documentation here...

How to use

import pyutau
import sys

plugin = pyutau.UtauPlugin(sys.argv[-1])

# Whatever you wanna do

plugin.write(sys.argv[-1])

UtauPlugin

UtauPlugin is the main class.

UtauPlugin(self, fpath)

Reads the UST data sent in by UTAU. The file path is always the second argument or the last argument.

---

Data descriptors:

version

Obsolete. Returns UST version. Will be None if not provided.

settings

Dictionary of UST settings. These are read-only. Will be empty when not provided. Read more about it in the @wiki page.

prev_note

Stores the note that precedes the selected notes in the UST. None if there is no PREV note.

next_note

Stores the note that succeeds the selected notes in the UST. None if there is no NEXT note.

notes

List that stores all notes. This uses the Note class.

---

Methods:

__str__(self)

Returns a string representation of the whole UST.

write(fpath, withHeader = False)

Writes the UST data to the given file path. Normally doesn't save header info.

insert_note(self, idx, note)

Inserts note at the given index. Notes are stored in a list.

delete_note(self, idx)

Sets the note at the given index to a DELETE note. Does not remove it from the list

get_notes(self)

Returns all notes that are not DELETE notes. I don't think you can modify notes directly without using mutable functions

Note

A class that stores note data.

Note(self, note_type = 'INSERT')

Makes a default note with the given note type. Note types are PREV, NEXT, INSERT, DELETE and ####. The default note is at C4 with lyric あ, and length 480

pyutau.create_note(lyric = 'あ', length = 480, note_num = 60, **kwargs)

Makes a new INSERT note. Made for inserting notes specifically. note_num is the key, C4 = 60. If the note is not a rest note (lyric "R", "r" or blank), it automatically sets intensity to 100 and mod to 0. **kwargs are for extra data. Read the @wiki mentioned above for more info.

---

Data descriptors:

note_type

Stores the note type. Does not change to DELETE when delete_note() is used

isdeleted

The reason why note_type doesn't change to DELETE with delete_note(). This is made in case someone wants to bring back a deleted note from their data

note_data

Where all note data is stored in a dictionary. Blank entries are written as None. Only put string keys and values here.

---

Methods:

__str__(self)

get(self)

Returns a string representation of the note in the format of the UST

delete_note(self)

Sets a note to a DELETE note without changing the note type.

get_note_type(self)

Returns the note type, and also responds to isdeleted. Use this one, don't read note_type directly

set_custom_data(self, name, data)

Sets in custom data and saves the string representation of the data under name.

get_custom_data(self, name)

Gets the string representation of the custom data under name

set_multiple_data(self, **kwargs)

Sets multiple data because note_data is a dictionary. Just.. yeah.

copy(self)

Returns a deep copy of the note.

clear_note(self)

Returns a clean slate note copy of the note with INSERT as its note type. Clean slate means it only has the required parameters plus intensity, modulation, and tempo. I think those are default essential. This is good for cleaning extra properties by removing the existing note and inserting the clean note, as UTAU never considers a property cleared when it's not returned.

Setters and Getters

These are written for data that UTAU can send in and read. Some of them get initializers because UTAU sends in values for them.

NOTE: All floating point data are rounded to 3 decimals when set. Sorry if you still wanted to keep precision.

NOTE pt. 2: If a property has both a setter and a getter, it's got a Python property setup for it. For example, since Lyric has both a setter and a getter, its property is named lyric. The set_lyric and get_lyric functions still exist for backwards compatibility, I hope. The table will list the property names, even if it doesn't have a setter. The format is just set_x, get_x, and init_x where x is the property name.

Legend: Required, Not Required, Read-only

Data Key	Property Name	Description	Getter	Setter	Initializer	Value Type
Length	length	Note Length. 480 = 1 quarter note.	✓	✓	-	int
Lyric	lyric	Note Lyric.	✓	✓	✓	str
NoteNum	note_num	Note key. C4 = 60	✓	✓	-	int
PreUtterance	preutterance	Note pre-utterance in milliseconds.	✓	✓	✓	float
VoiceOverlap	overlap	Note overlap in milliseconds.	✓	✓	✓	float
Intensity	intensity	Note intensity in percent.	✓	✓	-	float
Modulation	modulation	Note modulation in percent.	✓	✓	-	float
StartPoint	start_point	Note start point/time in milliseconds.	✓	✓	✓	float
Envelope	envelope	Note envelope.	✓	✓	-	Envelope
Tempo	tempo	Tempo at note in BPM.	✓	✓	-	float
Velocity	velocity	Note consonant velocity in percent.	✓	✓	-	float
Label	label	Label at note.	✓	✓	-	str
$direct	direct	Boolean that enables direct rendering.	✓	✓	-	bool
PBS, PBW, PBY, PBM	mode2pitch	Mode 2 pitchbend data.	✓	✓	-	Mode2Pitch
VBR	vibrato	Mode 2 vibrato data.	✓	✓	-	Vibrato
PitchBend, PBStart	mode1pitch	Mode 1 pitchbend data.	✓	✓	-	Mode1Pitch
@preuttr	at_preutterance	Re-calculated pre-utterance in milliseconds.	✓	-	-	float
@overlap	at_overlap	Re-calculated overlap in milliseconds.	✓	-	-	float
@stpoint	at_start_point	Calculated start point in milliseconds.	✓	-	-	float
@filename	sample_filename	Filename of sample.	✓	-	-	str
@alias	alias	Alias with prefix map applied. Can also have VCV applied for shareware.	✓	-	-	str
@cache	cache_location	Note cache file path. Not present when the note has no cache.	✓	-	-	str

Envelope

A class for storing envelope data. Largely based on how delta's library stores envelopes.

Envelope(envelope = '')

Makes an envelope from the string representation of it. Default envelope is 0, 5, 35, 0, 100, 100, 0 Read more about envelopes in the @wiki.

---

Data descriptors:

p

List of floats that store p1, p2, p3, p4, and p5. These are in milliseconds.

v

List of floats that store v1, v2, v3, v4, and v5. These are in percentages.

---

Methods:

__str__(self)

get(self)

Returns the string representation of the envelope.

set_all(self, *args)

Sets all of the parameters of the envelope to the arguments. Order of arguments is p1, p2, p3, v1, v2, v3, v4, (A '%' can be here, copes with UTAU's weirdness), p4, p5, v5.

copy(self)

Returns a deep copy of the envelope.

Mode1Pitch

A class for storing Mode1 pitchbend data. I gave my least efforts on this.

Mode1Pitch(PBStart = '', PitchBend = '')

Makes a new Mode1 pitchbend class from sting representations of Mode1 pitchbend data. Defaults are PBStart=None and PitchBend=0 Read more about Mode1Pitch in the @wiki.

---

Data descriptors:

start_time

Stores the start time of the pitchbend data anchored around the start of the note in milliseconds.

pitches

Stores the pitchbend values. I think the pitchbend data is in cents. I don't know how far two neighboring points are in milliseconds.

---

Methods:

set_pitches(self, *args)

Sets the pitchbend data to the arguments. Just use set_pitches(*some_list) when you have a list to put in.

get_pitches(self)

Returns the string representation of the pitchbend data. Just use some_mode1pitch_data.pitches to get the pitchbends in a list.

set_start_time(self, PBStart)

Sets the pitchbend's start time.

get_start_time(self)

Returns the string representation of the pitchbend's start time.

get(self)

Returns a dictionary with keys PBStart and PitchBend and values of the string representations.

copy(self)

Returns a deep copy of the Mode1 pitchbend data.

Mode2Pitch

A class for Mode2 pitchbend data.

Mode2Pitch(PBS = '-25', PBW = '50', PBY = '0', PBM = '')

Makes a new Mode2 pitchbend class from the string representations of Mode2 pitchbend data.

---

Data descriptors:

start_time

Stores the first control point's time anchored around the start of the note in milliseconds.

start_pitch

Stores the first control poin's pitch in decacents??? 10 in this value is one semitone or 100 cents.

pbw

Stores a list of intervals between the control points in milliseconds.

pby

Stores a list of offsets in pitch of the control points in decacents. I guess that's what we're calling it now.

pbm

Stores the pitchbend curves as a list of strings. Blank is S-curve, s is straight line/Linear, j is J-curve, and r is R-curve

---

Methods:

set_pbs(self, st, sp = 0)

set_pbw(self, *args)

set_pby(self, *args)

set_pbm(self, *args)

Sets the corresponding data.

get_pbs(self)

get_pbw(self)

get_pby(self)

get_pbm(self)

Gets the string representation of the corresponding data.

get(self)

Returns a dictionary with keys PBS, PBW, PBY, and PBM with its values as their corresponding data in their string representations.

copy(self)

Returns a deep copy of the Mode2 pitchbend data.

Vibrato

A class for storing Mode2 vibrato data.

Vibrato(VBR = '')

Makes a new Vibrato class for Mode2 vibrato data. Defaults are length 65, cycle 160, depth 35, fade in and out 20, the rest 0.

---

Data descriptors:

length

cycle

depth

fade_in

fade_out

phase

offset

These are pretty self explanatory. Offset is the Pitch in the Vibrato window. Units for these are percent, millisencond, cent, percent, percent, percent, and cent.

---

Methods:

set_all(self, length = None, cycle = None, depth = None, fade_in = None, fade_out = None, phase = None, offset = None)

Sets all vibrato data. I might write separate setters and getters for each but I can't be bothered for now.

__str__(self)

get(self)

Returns the string representation of vibrato.

copy(self)

Returns a deep copy of the vibrato.

---

You did it. You read through all of it... maybe...