CLI API

Command-line interface.

JSON output

--json produces a single machine-readable result on standard output for:

checkpoints
validate-project
test
info
train
tutorial
config explain
config profiles
config show
config get
config schema
config list

The formatting controls --json-indent and --json-ascii apply to these commands. Human-readable progress that accompanies a JSON result is written to standard error.

The following commands do not yet have a stable machine-readable result contract and reject --json with a nonzero exit status instead of silently producing human output. Unsupported JSON requests exit with status 64; parser usage errors retain status 2.

The rejecting commands are:

setup
build
split
features
flat
clean
package
align
compare
timings
config migrate
config path
step ci_hmm
step cd_hmm_untied

Place the global flag before the command name when checking support. Commands that support JSON also advertise it in their command help.

Command-line interface for pstrain.

The CLI provides commands for the complete acoustic model training workflow: - pstrain setup - Initialize a new project - pstrain validate-project - Validate project structure - pstrain split - Split data into train/test sets - pstrain features - Extract acoustic features - pstrain flat - Initialize flat HMM models - pstrain build - Build a model target (e.g. ci-1g, cd-8g) - pstrain package - Package a trained model for distribution - pstrain clean - Clean training outputs - pstrain config - Manage configuration - pstrain step - Run numbered training steps

All commands support --dry-run to preview actions without execution.

class pstrain.cli.Command[source]

Bases: ABC

Base class for CLI commands.

abstractmethod add_arguments(parser)[source]

Add command-specific arguments.

Parameters:: parser (ArgumentParser)
Return type:: None

description: str = ''

abstractmethod execute(ctx)[source]

Execute the command.

Parameters:: ctx (CommandContext)
Return type:: CommandResult

help: str = ''

name: str = ''

needs_config: bool = False

needs_experiment: bool = False

needs_project_dir: bool = True

register(subparsers)[source]

Register command with argument parser.

Parameters:: subparsers (Any)
Return type:: ArgumentParser

run(args)[source]

Run command with error handling.

Parameters:: args (Namespace)
Return type:: int

supports_dry_run: bool = True

supports_json_output: bool = False

class pstrain.cli.CommandContext(args, dry_run=False, verbose=False, json_output=False, json_indent=2, json_ascii=False, _header_emitted=False)[source]

Bases: object

Context passed to command execution.

Provides unified methods that either emit shell or execute directly.

Parameters:

args (Namespace)
dry_run (bool)
verbose (bool)
json_output (bool)
json_indent (int)
json_ascii (bool)
_header_emitted (bool)

__init__(args, dry_run=False, verbose=False, json_output=False, json_indent=2, json_ascii=False, _header_emitted=False)

Parameters:

args (Namespace)
dry_run (bool)
verbose (bool)
json_output (bool)
json_indent (int)
json_ascii (bool)
_header_emitted (bool)

Return type:

None

agg_seg(segdir, moddeffn, ctlfn)[source]

Aggregate segmentation statistics.

Parameters:

segdir (Path)
moddeffn (Path)
ctlfn (Path)

Return type:

None

args: Namespace

baum_welch(mdef, mean, var, mixw, tmat, ctl, cepdir, dictfn, lsnfn=None, accumdir=None, cepext='.mfc')[source]

Run Baum-Welch training.

Parameters:

mdef (Path)
mean (Path)
var (Path)
mixw (Path)
tmat (Path)
ctl (Path)
cepdir (Path)
dictfn (Path)
lsnfn (Path | None)
accumdir (Path | None)
cepext (str)

Return type:

None

blank()[source]

Add a blank line in dry-run output.

Return type:: None

build_tree(moddeffn, meanfn, varfn, mixwfn, psetfn, treefn, phone, state)[source]

Build decision tree.

Parameters:

moddeffn (Path)
meanfn (Path)
varfn (Path)
mixwfn (Path)
psetfn (Path)
treefn (Path)
phone (str)
state (int)

Return type:

None

comment(text)[source]

Add a comment (no-op when executing).

Parameters:: text (str)
Return type:: None

property config_name: str: Get config name.

copy(src, dst)[source]

Copy file.

Parameters:

src (Path | str)
dst (Path | str)

Return type:

None

copy_tree(src, dst)[source]

Copy directory tree.

Parameters:

src (Path | str)
dst (Path | str)

Return type:

None

dry_run: bool = False

emit_blank()[source]

Alias for blank.

Return type:: None

emit_json(data, output_path=None)[source]

Serialize JSON once and emit identical bytes to its destinations.

Parameters:

data (Any)
output_path (Path | None)

Return type:

None

error(message)[source]

Log an error message.

Parameters:: message (str)
Return type:: None

property experiment: str: Get experiment name.

extract_features(input_file, output_file, samprate=16000, nfilt=25, ncep=13)[source]

Extract features from audio file.

Parameters:

input_file (Path)
output_file (Path)
samprate (int)
nfilt (int)
ncep (int)

Return type:

None

format_json(data)[source]

Format data as JSON using context settings.

Parameters:: data (Any)
Return type:: str

json_ascii: bool = False

json_indent: int = 2

json_output: bool = False

log(message)[source]

Log a message.

Parameters:: message (str)
Return type:: None

log_action(action, target)[source]

Log an action being performed.

Parameters:

action (str)
target (str)

Return type:

None

log_comment(text)[source]

Alias for comment.

Parameters:: text (str)
Return type:: None

make_quests(moddeffn, meanfn, varfn, mixwfn, questsfn)[source]

Generate phonetic questions.

Parameters:

moddeffn (Path)
meanfn (Path)
varfn (Path)
mixwfn (Path)
questsfn (Path)

Return type:

None

mkdir(path, parents=True)[source]

Create directory.

Parameters:

path (Path | str)
parents (bool)

Return type:

None

normalize(accumdir, meanfn, varfn, mixwfn, tmatfn)[source]

Normalize BW accumulators.

Parameters:

accumdir (Path)
meanfn (Path)
varfn (Path)
mixwfn (Path)
tmatfn (Path)

Return type:

None

property project_dir: Path: Get resolved project directory.

pstrain(*args, **kwargs)[source]

Run pstrain CLI command (for nested pstrain calls in dry-run).

Parameters:

args (str)
kwargs (Any)

Return type:

None

remove(path, recursive=False, force=False)[source]

Remove file or directory.

Parameters:

path (Path | str)
recursive (bool)
force (bool)

Return type:

None

run_cmd(program, *args, cwd=None, **kwargs)[source]

Run a shell command.

Parameters:

program (str)
args (str)
cwd (Path | None)
kwargs (Any)

Return type:

None

split_gaussians(inmeanfn, invarfn, inmixwfn, outmeanfn, outvarfn, outmixwfn)[source]

Split Gaussian components.

Parameters:

inmeanfn (Path)
invarfn (Path)
inmixwfn (Path)
outmeanfn (Path)
outvarfn (Path)
outmixwfn (Path)

Return type:

None

symlink(src, dst)[source]

Create symlink.

Parameters:

src (Path | str)
dst (Path | str)

Return type:

None

tie_states(imoddeffn, omoddeffn, treedir, psetfn)[source]

Tie states using decision trees.

Parameters:

imoddeffn (Path)
omoddeffn (Path)
treedir (Path)
psetfn (Path)

Return type:

None

verbose: bool = False

write_file(path, content)[source]

Write content to file.

Parameters:

path (Path | str)
content (str)

Return type:

None

class pstrain.cli.CommandResult(success, message='', data=<factory>, exit_code=0)[source]

Bases: object

Result of command execution.

Parameters:

success (bool)
message (str)
data (dict[str, Any])
exit_code (int)

__init__(success, message='', data=<factory>, exit_code=0)

Parameters:

success (bool)
message (str)
data (dict[str, Any])
exit_code (int)

Return type:

None

data: dict[str, Any]

exit_code: int = 0

classmethod fail(message, exit_code=1)[source]

Create failure result.

Parameters:

message (str)
exit_code (int)

Return type:

Self

message: str = ''

classmethod ok(message='', data=None)[source]

Create successful result.

Parameters:

message (str)
data (dict[str, Any] | None)

Return type:

Self

success: bool

class pstrain.cli.ModelCommand[source]

Bases: ProjectCommand

Command that operates on models within a project.

add_model_arguments(parser)[source]

Add common model arguments.

Parameters:: parser (ArgumentParser)
Return type:: None

default_model_type: str = 'ci'

get_model(ctx)[source]

Create model instance from args.

Parameters:: ctx (CommandContext)
Return type:: Any

needs_config: bool = True

class pstrain.cli.ProjectCommand[source]

Bases: Command

Command that operates on a project directory.

get_config(ctx)[source]

Load project configuration.

Parameters:: ctx (CommandContext)
Return type:: Any

needs_config: bool = False

needs_experiment: bool = True

needs_project_dir: bool = True

pstrain.cli.main()[source]

Return type:: int