setParam Plugin Development Guidelines rev 1

English Translation

Tags:
  1. Kiyoteru
    setParam Automatic Estimation Plugin Development Guidelines
    (version 3.0-b150712 onwards)​

    created 2013/01/23
    revised 2015/07/12​
    [hr]

    This document explains how to develop plugins for setParam, a program for editing UTAU voicebank parameters.

    Plugin specifications were created in setParam ver.2.0-b130130.
    Afterwards, specifications were changed in ver.3.0-b150712 to allow the following three types of plugins.

    (a) Editing all entries (automatic estimation, etc.)
    (b) Editing the currently displayed entry in the waveform window
    (c) Editing multiple entries selected in the table window​

    [hr]
    Plugin Installation Location

    Create a new folder in "path\to\setParam\plugins\" for the executable and plugin.txt files.

    [hr]
    Plugin Execution Process

    Plugin execution follows this procedure.

    1) setParam creates the text file "path\to\setParam\plugins\inParam.txt"
    This file's contents have the following format.

    [hr]
    Line 1: Absolute path to voicebank folder
    Line 2: Absolute path to voicebank parameter temp file during plugin execution
    Line 3: F0 sampling interval (seconds)
    Line 4: Power sampling interval (seconds)
    Line 5: Line number of currently displayed entry in setParam's waveform window
    Index starts at 1​
    Line 6: Line number of selected entry/entries in setParam's table window
    When multiple are selected, line numbers are separated by commas​
    [hr]

    Example of inParam.txt
    [hr]
    C:/voicebank/example
    C:/voicebank/example/oto-autoEstimation.ini
    0.01
    0.02
    5
    3,4,5
    [hr]

    Paths in lines 1 and 2 use Tcl/Tk formatting rather than Windows formatting.
    If a folder appears like "C:\foo\bar" in Windows, it appears as "C:/foo/bar" in Tcl/Tk (Backslashes become forward slashes)​

    2) setParam saves the current voicebank parameters to the file path specified in line 2.

    3) If the plugin settings file (plugin.txt) specifies "needF0=1", F0 files for all wav files will be generated. Additionally, if "needPower=1" is specified, power files for all wav files will be generated.

    4) Plugin executes. The plugin should read inParam.txt and other files, edit the voicebank parameters, and write to the file specified in line 2 of inParam.txt.

    5) setParam imports the file specified in line 2 of inParam.txt. At that time, the plugin type specified in the plugin settings file (plugin.txt) will determine how the changes are applied (to all entries or to selected entries only).

    [hr]
    About plugin.txt

    During startup, setParam reads all "path\to\setParam\plugins\*\plugin.txt" files and adds those plugins to the menu.

    The following entries can be written in plugin.txt.
    "name" and "execute" are required.
    Other entries should only be specified as necessary (Please omit unnecessary lines).

    name=Automatic CV estimation: hogehoge ← Name shown in setParam
    execute=hogehoge.exe ← Plugin execution command
    argv=-a %S -b %n ← Plugin execution arguments (details later)
    needF0=0 ← Set 1 to require F0 data (details later)
    F0unit=semitone ← Set F0 unit (Hz or semitone)
    needPower=0 ← Set 1 to require power data (details later)
    edit=all ← Plugin behavior type (details later)​

    [hr]
    About argv in plugin.txt

    The string specified in "argv=" will be passed to the plugin as arguments upon execution.
    If the following abbreviations are used in the arguments string, they will be replaced before passing to the plugin as follows.

    %S ← Absolute path to voicebank folder
    %s ← Absolute path to voicebank folder
    For backwards compatibility with old plugins, paths including spaces will result in a broken string.​
    %R ← Absolute path to voicebank parameter temp file during plugin execution
    %r ← Absolute path to voicebank parameter temp file during plugin execution
    For backwards compatibility with old plugins, paths including spaces will result in a broken string.​
    %f ← F0 sampling interval (seconds)
    %p ← Power sampling interval (seconds)
    %n ← Line number of currently selected entry in wavedorm window
    %l ← List of currently selected line numbers in voicebank parameter temp file
    ex. if lines 2 to 4 are selected, it will be a comma separated string like "2,3,4"​

    Additionally, %S, %s, %R, and %r uses Tcl/Tk formatting rather than Windows formatting.
    If a folder appears like "C:\foo\bar" in Windows, it appears as "C:/foo/bar" in Tcl/Tk (Backslashes become forward slashes)

    Furthermore, if a folder name includes spaces like "C:/Program Files/", %s and %r will break the string into "C:/Program" and "Files/". Because of that, please use $S and $R as much as possible for importing the values of lines 1 and 2 from inParam.txt.

    [hr]
    About needF0 and F0unit in plugin.txt

    If "needF0=1" is written in plugin.txt, upon running the plugin, setParam will generate text files of F0 data for all wav files.
    • F0 file name:
      wav file extension is replaced with ".setParam-f0"
      (ex. F0 file of "a.wav" is "a.setParam-f0")

    • F0 files location:
      Same folder as wav files.

    • File contents:
      One F0 value per line, listed vertically.
      F0 values will use the unit specified in "F0unit" from plugin.txt.
      In addition, F0 sampling parameters use F0 values shown on screen in setParam.
    [hr]
    About needPower in plugin.txt

    If "needPower=1" is written in plugin.txt, upon running the plugin, setParam will generate text files of power data for all wav files.
    • Power file name:
      wav file extension is replaced with ".setparam-power".
      (ex. power file of "a.wav" is "a.setparam-power")

    • Power files location:
      Same folder as wav files.

    • File contents:
      One power value per line, listed vertically.
      Power sampling parameters use power values shown on screen in setParam.
      Units are dB.
    [hr]
    About edit in plugin.txt

    A new plugin will eventually have to specify one of the following behaviors.
    • Edit only the currently displayed entry in setParam's waveform window
      → edit=single
    • Edit only the selected entries in setParam's table window
      → edit=region
    • Edit all entries
      → edit=all
    When importing the plugin results, setParam will use the value of "edit" to apply to selected lines only or replace all lines, like the following examples.

    Ex 1: If the 3rd line from oto.ini is currently displayed and a plugin with "edit=single" is run, setParam will skip the first 2 lines and import the 3rd line only.

    Ex 2: If lines 3, 4, and 7 of the oto.ini are selected in the table window and a plugin with "edit=region" is run, setParam will skip the first 2 lines and and import lines 3-7.

    Ex 3: If a plugin with "edit=all" is run, setParam will import the entire results file.

    [hr]
    Other

    Plugin specifications may change in the future.
    If you have requests such as "I'd like setParam to output this sort of data" or "I'd like to input this sort of data to setParam" I would be glad to receive blog comments, etc.
    http://nwp8861.blog92.fc2.com/
    https://twitter.com/nwp8861