syllabler Song Syllable Labeler

Interactive tool to view spectrograms for a folder of WAV files and label syllables by time span. Labels are colored consistently and can be reassigned in bulk.

Installation

• Create a fresh conda environment, then install Python packages with pip.

conda create -n song-syllabler python=3.13 git uv -y
conda activate song-syllabler
uv pip install git+https://github.com/janclemenslab/syllabler.git

Local install

git clone https://github.com/janclemenslab/syllabler.git
cd syllabler
pip install -e .

Run

syllabel --songs PATH_TO_SONGS [--annotations PATH_TO_GLOBAL_CSV]

• --songs is required. It should point to a folder with .wav files.
• If --annotations is omitted, it defaults to <songs>/<basename(songs)>.csv. For example, if the folder is ABC/, the default is ABC/ABC.csv.
• Export CSV also defaults to this path.

Usage

• Select: Click a colored syllable block in the spectrogram view to toggle selection.

• Assign labels: Use "Assign Auto-Name" or "Assign Custom Name…" or click on syllable name in the syllable list on the right.

• Propose labels: Click "Propose Labels" to run an automatic labeling algorithm over all files in the songs folder and populate names.

• Edit mode [E]:

  • Left‑click empty space to add a syllable: first click sets the start (cursor changes to crosshair), second click sets the stop. Right‑click or ESC cancels while adding.
  • Drag edges to resize (cursor shows horizontal resize near boundaries).
  • Drag inside to move horizontally (cursor shows closed hand while dragging).
  • Right‑click a syllable to delete it.

• Lasso: Click‑drag horizontally to select multiple; right‑click any selected syllable deletes all selected.

• Navigation: UP zooms in, DOWN zooms out, LEFT/RIGHT pans time.

Syllables can also be selected

• Left-click on a row applies that name to all currently selected syllables.
• Right-click on a row selects every syllable with that name across all rows.
• Ctrl+right-click on a row toggles a visibility filter to show only that name; clicking again when already filtered clears the filter.
• The “Show All Types” button above the list clears any visibility filter so every syllable type is shown again.

Annotations

• Per‑file CSVs: For each <file>.wav, an adjacent <file>_annotations.csv may provide syllables.
• Global CSV (optional): Pass --annotations <path> for a combined CSV.
• Expected columns:
  • Per‑file: start_seconds, stop_seconds, name
  • Global: filename, start_seconds, stop_seconds, name

Export

• Use "Export CSV…" to write all current syllables for all rows into a single CSV.

Code and icon generated by ChatGPT5.