GUI¶

Triton includes a Streamlit GUI for project-oriented workflows.

Run¶

triton gui (pip install) or pixi run gui (from a clone)
UI theme is forced to dark mode via project Streamlit config (.streamlit/config.toml).

Developer Layout¶

The GUI is now split by responsibility so app.py stays focused on page-level orchestration:

triton.gui.app: app bootstrap, page setup, and top-level routing
triton.gui.shared: shared helpers used across multiple tabs
triton.gui.tabs.file_library: Manage and Explore Files tab UI
triton.gui.tabs.pipelines: Pipelines tab UI and controls
triton.gui.tabs.rss: RSS ingest tab UI
triton.gui.tabs.classify: Classify tab UI
triton.gui.tabs.features: Features tab UI
triton.gui.assets.app.css: GUI stylesheet loaded at app startup

When adding a new tab, place tab-specific rendering logic in triton.gui.tabs.<name> and keep cross-tab helpers in triton.gui.shared.

Project Dashboard¶

When the app opens, you start from a project launcher:

Recent (default): quickly reopen recently used projects
Open: open an existing project directory from anywhere on disk
Create: create a new project with canonical audio settings (sample rate and channel mode)

When creating a project, you define the full audio spec: sample rate, channel mode (mono/stereo), bit depth (8/16/24/32), and file format (wav/flac/ogg). You can also set spectrogram defaults (type and parameters). All settings are persisted into triton.toml.

Project Structure¶

Each project stores config and data inside its own directory:

<project>/
  triton.toml
  data/
    raw/
    normalized/
    derived/
  metadata/

Manage and Explore Files Tab¶

The Manage and Explore Files tab is the default project workspace entry point for managing source files and their labels.

Import Files¶

import one or more audio files; originals are saved to data/raw/ and a normalized copy (matching the project spec) is written to data/normalized/ automatically
optionally set a filename prefix to prepend to all imported files (useful when different sources share the same original filenames)
optionally assign one label to the full upload batch during import
view files in a compact list with metadata (name, size, format, labels)
play audio inline per file
rename or remove files (also removes the matching raw counterpart)
open a precomputed spectrogram per file in the right-side spectrogram panel (spectrogram is generated from the normalized file)

After importing, the file browser selection and upload widget are automatically reset to allow for a clean next import.

Example Files¶

The No audio handy? Add example files expander (open automatically on an empty project) downloads the HARVARD speech-in-noise corpus once to ~/.cache/triton/examples, verifies each file's SHA-256, and imports the four files into the project:

Harvard_speech100.wav, labeled harvard-speech
speech-shaped, speech-modulated and white noise, labeled harvard-noise

Files already in the project are skipped. See CLI → examples for source and license (CC BY-NC 4.0).

Label Files¶

Each file in the list has a Label text field. Enter one or more comma-separated labels (e.g. bab-f1, studio). Labels are saved immediately when you commit the field (press Enter or tab away).

The Filter by label dropdown filters the list; select (None) to show only files with no labels.
Label counts are shown in the Manage Labels expander alongside each label name.

Manage Labels¶

The Manage Labels expander (above the file list) provides:

Rename a label¶

Rename an existing label to apply the new name to all files that currently have that label. Useful for:

correcting label typos across multiple files
reorganizing labels (e.g., renaming all talker labels to bab-f1)
preparing files for babble generation with consistent naming (e.g., bab-f1, bab-m1)

On multi-label files, only the target label is replaced; other labels are preserved.

Bulk label unlabeled files¶

Enter a label and click Apply to assign it to every file that currently has no labels. Useful for quickly categorizing a freshly imported batch.

Bulk Delete by Label¶

You can remove all imported files associated with a label directly in the Manage and Explore Files tab.

in Bulk Actions, select a label in Delete all files with label
check Confirm
click Delete Label Files

This removes all normalized files with that label, removes matching raw-source files, and updates label metadata.

Imported files automatically trigger spectrogram computation using project defaults from triton.toml ([spectrogram] section).

Spectrogram artifacts are stored next to source files:

example.wav -> example.wav.spectrogram.npz
sidecar metadata: example.wav.spectrogram.npz.json

The Spec button selects the file and displays this precomputed artifact in the right panel.

Spectrogram viewer behavior:

rendered as an interactive Plotly heatmap (zoom/pan/scroll)
time/frequency axes are shown directly in the chart
inferno colormap is used for display
large spectrograms are downsampled for responsive interaction (shown in the panel caption)

Accessibility and deprecation cleanup in the Import list:

hidden labels are non-empty to avoid Streamlit accessibility warnings
deprecated use_container_width usage has been replaced with width="stretch"

Mix Tab¶

Mix speech and noise interactively:

upload speech and noise audio
set target SNR
preview result and download mixed output

Inputs are normalized in-session to project audio settings before mixing.

Babble Tab¶

Generate babble speech from labeled talker groups:

select the total number of talker groups to mix
optionally set female and male counts separately
optionally assign the same label to an uploaded batch in the Import tab
use labels such as bab-f1, bab-f2, bab-m1, and bab-m2
set an intended per-talker output length
normalize each source file to the target RMS before concatenating files for the same talker
optionally peak-normalize the mixed output to prevent clipping
monitor a progress bar and a live status console while babble is generated
download the generated babble for use in experiments
add the generated babble back into the project as a derivative artifact labeled bab-t#, where # is the number of talkers used

When you add a generated babble to the project, Triton stores a provenance sidecar alongside the audio. The sidecar records the source files, babble parameters, intended length, RMS settings, and other generation details so the derivative can be traced and reproduced later.

If no sex split is provided, Triton balances female and male talkers as evenly as possible. When multiple files share a babble label, they are concatenated in filename order after RMS normalization.

If source material for a selected talker is shorter than the intended length, Triton warns and randomly repeats that talker's files until target length is reached.

Babble generation in the GUI and CLI both use the same shared core function in triton.degrade.noise_generator, so file selection, loading, and mixing behavior are consistent.

Typical workflow:

Import audio files in the Manage and Explore Files tab, optionally assigning a batch label
Edit labels individually in the file table, or rename multiple labels at once using the "Rename Labels" panel
Go to the Babble tab
Review the available babble talker groups (labeled with bab-f1, bab-m1, etc.)
Set the total number of talkers, then optionally set female and male counts
Set intended length, then adjust target RMS and peak normalization settings
Click "Generate Babble"
Use Download to save the output locally or Add to project to persist it as a labeled derivative with provenance metadata

Pipelines Tab¶

The Pipelines tab is the project processing workspace.

select an existing pipeline
run it on one or more project files
create/edit pipelines from the right-side editor
define ordered steps and step-specific options

Pipeline Run Storage¶

Each pipeline execution creates a dedicated run folder and each step writes to its own subfolder:

data/derived/pipelines/<pipeline_key>/run_<timestamp>_<id>/
  step_01_<step_key>/
  step_02_<step_key>/
  ...

For each processed input file, every step emits a step artifact (.wav) and a sidecar provenance JSON (.wav.json).

The Run Pipelines tab shows a live progress bar while files are being processed.

Matrix CSV Storage¶

Matrix CSVs generated in the GUI are saved under:

metadata/matrices/<pipeline_name>/<pipeline_name>.matrix.csv

In Pipeline Matrix → Generate Matrix, selecting a pipeline immediately refreshes the displayed step/option controls for that pipeline.

In Pipeline Matrix → Run Matrix, you can choose a source mode:

Saved: browse and select matrix CSVs already stored for the selected pipeline
Upload: upload a CSV from your local machine
Path: provide an absolute or project-relative CSV path

In Pipeline Matrix → Run Matrix, selecting a pipeline immediately refreshes the saved matrix list for that pipeline.

The Matrix Run panel also shows a live row-by-row progress bar while rows are executed, and it can optionally collect only final outputs into final_by_params/set_####_* folders for each parameter combination.

Add Noise Step¶

The pipeline editor includes an add_noise step with these options:

noise_type: auto, babble, white, colored, ssn
snr_db: target SNR in dB
noise_project_file: select a noise source from existing project audio files
seed: optional random seed

Notes:

babble in this step is file-backed only and is not generated.
With noise_type=auto, files named like bab-t8.wav are auto-recognized as multitalker babble sources.
If the provided noise is longer than the speech signal, Triton randomly selects a same-length segment before mixing.

Sidecar Provenance¶

Step sidecars include:

source file path
ordered action history up to that step
step options and sample-rate transitions
pipeline name/run identifier

Project Spectrogram Defaults¶

Project spectrogram defaults are persisted in triton.toml:

type (stft, mel, cqt)
n_fft
hop_length
win_length
window
n_mels
fmin
fmax
power

These defaults are used when importing files to precompute spectrograms.

RSS Ingest Tab¶

Fetch and download podcast episodes directly into a project from an RSS feed.

enter a feed URL and set a max episode limit
optionally filter by publish date (preset ranges: last 7 / 30 / 90 days, or custom dates)
preview matching episodes before downloading
download episodes; each file is normalized to the project spec and a spectrogram is generated
downloaded episodes land in data/raw/ first, then normalized copies are written to data/normalized/

Transcribe Tab¶

Speech-to-text with OpenAI Whisper, run locally.

pick a file and a model size (tiny → large; larger is more accurate and slower)
optionally set the language code, or leave blank for auto-detect
shows the full transcript and a table of timed segments

Requires the transcribe extra.

Classify Tab¶

Tags what a recording contains using the Audio Spectrogram Transformer, trained on AudioSet's 527 sound classes (speech, music, vehicles, birds, …).

select one or more files and how many top labels to show
results table with a confidence per label
Add top label to project appends the best label to the file's existing labels, so labels such as bab-f1 are kept and the new label can be used for filtering

AST reads roughly the first 10 seconds of each file. Requires the classify extra.

Features Tab¶

Extracts time-aligned features for relating audio to brain recordings (EEG/MEG), in the spirit of Kell et al. (2018) and Gwilliams et al.

Feature	Saved arrays	Rate
Amplitude envelope	`times`, `envelope`	configurable (default 100 Hz)
Word onsets	`words`, `onsets`, `offsets`, `times`, `onset_train`	same grid as the envelope
Neural network layers	`times`, `hidden_states` (layers × frames × 768), `layers`	50 Hz

Envelope: magnitude of the analytic signal, |hilbert(x)|, low-passed (default 30 Hz) and resampled. This differs from core.signal.extract_envelope(method="hilbert"), which rectifies first and leaks energy before sound onsets.
Word onsets: from Whisper word-level timestamps. onset_train has a 1 at each word onset and exactly the same length as the envelope, so the two can be stacked directly.
Neural layers: hidden states from Wav2Vec2, HuBERT or WavLM (base models, 12 transformer layers). Layer 0 is the input to the first transformer layer. Long files are processed in 20 s chunks to bound memory.

Output layout (each .npz also embeds its settings as meta_json):

data/derived/features/<file stem>/
  <stem>.envelope.npz        + .npz.json sidecar
  <stem>.word_onsets.npz     + .npz.json sidecar
  <stem>.<model>.npz         + .npz.json sidecar

Features move with their audio file on rename and are removed on delete. The preview shows the envelope with word markers and, on request, a z-scored layer-by-time activity heatmap.

Loading a file in Python:

import numpy as np
data = np.load("data/derived/features/talker1/talker1.wav2vec2.npz")
data["hidden_states"].shape   # (13, n_frames, 768)
data["times"]                 # frame centres in seconds

Word onsets and neural layers require the features extra.