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
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...
import pyutau
import sys
plugin = pyutau.UtauPlugin(sys.argv[-1])
# Whatever you wanna do
plugin.write(sys.argv[-1])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.
- 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.
- __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
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.
- 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.
- __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.
Legend: Required, Not Required, Read-only
| Data Key | Description | Setter | Getter | Initializer | Value Type |
|---|---|---|---|---|---|
| Length | Note Length. 480 = 1 quarter note. | set_length(self, length) |
get_length(self) |
- | int |
| Lyric | Note Lyric. | set_lyric(self, lyric) |
get_lyric(self) |
init_lyric(self) |
str |
| NoteNum | Note key. C4 = 60 | set_note_num(self, note_num) |
get_note_num(self) |
- | int |
| PreUtterance | Note pre-utterance in milliseconds. | set_preutterance(self, preutterance) |
get_preutterance(self) |
init_preutterance(self) |
float |
| VoiceOverlap | Note overlap in milliseconds. | set_overlap(self, overlap) |
get_overlap(self) |
init_overlap(self) |
float |
| Intensity | Note intensity in percent. | set_intensity(self, intensity) |
get_intensity(self) |
- | float |
| Modulation | Note modulation in percent. | set_modulation(self, modulation) |
get_modulation(self) |
- | float |
| StartPoint | Note start point/time in milliseconds. | set_start_point(self, start_point) |
get_start_point(self) |
init_start_point(self) |
float |
| Envelope | Note envelope. | set_envelope(self, envelope) |
get_envelope(self) |
- | Envelope |
| Tempo | Tempo at note in BPM. | set_tempo(self, tempo) |
get_tempo(self) |
- | float |
| Velocity | Note consonant velocity in percent. | set_velocity(self, velocity) |
get_velocity(self) |
- | float |
| Label | Label at note. | set_label(self, label) |
get_label(self, label) |
- | str |
| $direct | Boolean that enables direct rendering. | set_direct(self, direct) |
get_direct(self) |
- | bool |
| PBS, PBW, PBY, PBM | Mode 2 pitchbend data. | set_mode2pitch(self, mode2pitch) |
get_mode2pitch(self) |
- | Mode2Pitch |
| VBR | Mode 2 vibrato data. | set_vibrato(self, vibrato) |
get_vibrato(self) |
- | Vibrato |
| PitchBend, PBStart | Mode 1 pitchbend data. | set_mode1pitch(self, mode1pitch) |
get_mode1pitch(self) |
- | Mode1Pitch |
| @preuttr | Re-calculated pre-utterance in milliseconds. | - | get_at_preutterance(self) |
- | float |
| @overlap | Re-calculated overlap in milliseconds. | - | get_at_overlap(self) |
- | float |
| @stpoint | Calculated start point in milliseconds. | - | get_at_start_point(self) |
- | float |
| @filename | Filename of sample. | - | get_sample_filename(self) |
- | str |
| @alias | Alias with prefix map applied. Can also have VCV applied for shareware. | - | get_alias(self) |
- | str |
| @cache | Note cache file path. Not present when the note has no cache. | - | get_cache_location(self) |
- | str |
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.
- 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.
- __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.
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.
- 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.
- 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.
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.
- 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
- 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.
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.
- 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.
- 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...