# TTML Tool Feature Reference

# TTML Tool Feature Reference

The **NaeNae AMLL TTML Tool** is an editor for creating, timing, checking, previewing, and exporting synced lyrics. The [TTML creation guide](https://guides.spicylyrics.org/s/ttml) teaches the normal start-to-finish workflow. This page is the reference for everything else: what each feature does, when it is useful, and where to find it.

> **New here?** Follow the creation guide first. You do not need every feature on this page to make a good TTML. Come back when you encounter a button you do not understand or need to repair something specific.

The interface has three main modes at the top:

* **Edit** prepares the lyric text and its structure.
* **Time** synchronizes words or lines to the audio.
* **Preview** shows how the finished lyrics behave in different renderers.

Use **Advanced** at the end of a mode's ribbon to reveal less common controls.

## Starting and managing a project

### New lyrics

**What it does:** Clears the editor and starts a new TTML project.

**When to use it:** When beginning another song rather than replacing the lyrics inside the current project.

**Where:** **File → New lyrics** or `Ctrl+N` (`Cmd+N` on macOS).

### Import lyrics

**What it does:** Brings lyric text or existing timed lyrics into the editor.

**Where:** The empty-editor import cards, or **File → Import lyrics**.

Available sources include:

* **Plain text:** best for lyrics copied from a trusted source. The preparation screen can clean the text, recognize section headers, and arrange lines before insertion.
* **LRCLIB:** searches LRCLIB for plain, line-synced, or enhanced lyrics.
* **Lyrically:** searches the Lyrically service.
* **Genius:** searches Genius and can preserve headers such as `[Verse]` and `[Chorus]` as sections.
* **LRC / enhanced LRC, QRC, YRC, and Lyricify Syllable:** converts supported existing lyric files into the editor's internal format.

Importing is a starting point, not proof that the words or timing are correct. Review everything against the song.

### Open lyrics / Open TTML from clipboard

**What it does:** Opens an existing TTML file, or parses TTML already copied to the clipboard.

**When to use it:** To continue an existing project, review somebody else's work, or quickly inspect TTML without first saving it as a file.

**Where:** **File → Open lyrics**, **File → Open TTML from clipboard**, or `Ctrl+O` / `Cmd+O`.

### Save lyrics / Save TTML to clipboard

**What it does:** Validates and exports the current project as TTML. The clipboard option copies the generated TTML instead of downloading or saving a file.

**When to use it:** Save normally for submission and testing. Use the clipboard for quick inspection or transferring the file into another tool.

**Where:** **File → Save lyrics**, **File → Save TTML to clipboard**, or `Ctrl+S` / `Cmd+S`.

The pre-export validator warns about problems such as untimed content or invalid overlaps. Do not ignore a warning unless you understand why the structure is intentional.

### Project history and recovery

**What it does:** Stores local project snapshots and lets you restore an earlier state.

**When to use it:** After an accidental deletion, bad bulk edit, or when you need a version from before the latest save.

**Where:** **File → Restore from history…**. Auto-save behavior and the number of snapshots kept are under **Edit → Preferences → Files & Storage**.

History is local to that browser profile or desktop installation. It is not a cloud backup.

### Folder projects and linked projects (desktop)

**What they do:** Keep a song's TTML, audio, and metadata together as a project you can reopen later, instead of juggling loose files.

**When to use them:** When you work on the same songs over several sessions and want the tool to remember where everything is.

**Where:** Folder projects are **opt-in**: enable them under **Preferences → Files & Storage**, then use **File → Projects**. When you load lyrics together with audio, the app offers to create a project.

* **Create** builds a project folder (named after the song, or `Untitled Song-1`, `Untitled Song-2`, and so on) containing a `project.json` manifest plus your files.
* **Keep files in place** creates a *linked* project instead. Your TTML and audio stay where they are, and the project only stores their locations. Nothing is written when linking or autosaving. An explicit save writes the TTML back to the original file, after making a one-time backup of the original in the project's data folder.
* The **Projects** window has Recent, Linked, and Workspace tabs with a search field, an **Open projects folder** button, and labels showing whether each entry is a folder or linked files.
* Inside a project, `Ctrl+S` / `Cmd+S` saves the project instead of exporting standalone TTML. Unsaved changes still trigger a warning before you open something else, and saving keeps your undo history.
* The project folder follows the song metadata when you save, but folders you renamed yourself are never touched. The manifest carries a project identifier and song fingerprint, so files are still found after being renamed outside the app.

Folder access is granted only through folders you pick in the native dialog.

## Editing lyric structure

### Selecting lines and words

Click a line or word to select it. Modifier keys let you build a larger selection. The **Edit** menu also provides:

* **Select all lines** (`Ctrl+A` / `Cmd+A`)
* **Deselect all lines** (`Ctrl+Esc` / `Cmd+Esc`)
* **Invert line selections**
* **Select words matching selection** (`Ctrl+F2` / `Cmd+F2`), useful for changing every occurrence of the same word
* **Delete selected words** (`Delete`, or `Backspace` on macOS)

Most ribbon fields and context-menu actions apply to the current selection. If an action appears to do nothing, check what is selected.

### Add, insert, duplicate, combine, and delete lines

**What they do:** Change the number and order of lyric lines.

**Where:** Use **Edit → New → Lyric Line** to append a line. Right-click a line for **Insert before**, **Insert after**, **Duplicate**, **Duplicate to…**, **Combine lines**, and **Delete**.

**When to use them:**

* Insert a line when a vocal was missed.
* Duplicate a line for a repeated phrase, then edit its words.
* **Duplicate to…** copies a line to a chosen time position.
* Combine lines when an imported source broke one sung phrase into the wrong structure.

### Split, combine, replace, and move words

**Where:** Right-click a word or a selection of words.

* **Split word…** manually divides a word into timed syllable chips.
* **Split into Syllables (Romanized)** uses phonetic information to propose syllables.
* **Combine words** joins selected adjacent chips. The dedicated dialog can preview the result and optionally apply the same combination elsewhere.
* **Replace word…** changes matching occurrences of a word.
* **Replace romanization…** changes matching per-word readings.
* **Move following words to new line** splits the line at that point.
* **Move selected words to new line** moves only the selection.

Use these tools to make the chips follow what is actually sung. Do not split purely by spelling when the pronunciation groups sounds differently. See the [Splitting Guidelines](https://guides.spicylyrics.org/s/splitting/doc/splitting-guidelines-IyXtGi4ta6) for the accepted standards.

### Auto Segment, Ruby Segmentation, and Advanced Segment

**What they do:** Break unsplit lyric words into syncable units.

**Where:** **Tools → Segmentation Tools**. Auto Segment also defaults to a double-tap of `E`.

* **Auto Segment** chooses or suggests a language-aware splitter.
* **Ruby Segmentation** uses pronunciation/ruby information, especially for CJK text.
* **Advanced Segment…** lets you choose and configure the segmentation engine.
* **Learned Splits…** shows boundaries remembered from previous manual corrections. These can be reused when the same word appears again.

Automatic segmentation is a suggestion. Check unusual names, contractions, stylized spelling, and multilingual lines manually.

### Sections

Genius-style headers such as `[Verse]`, `[Chorus]`, and `[Bridge]` can become section metadata rather than sung text. Sections are color-coded and provide actions for selecting or adjusting the whole section.

**When to use them:** For navigation and bulk operations on a logical part of a song. A section label itself should not become a lyric line unless it is audibly sung.

## Line and word properties

Select lines or words in **Edit** mode to expose their fields in the ribbon.

### Start time, end time, and duration

**What they do:** Directly edit the timestamps of the selected line or word. The end-time field can be displayed as an absolute timestamp or duration.

**When to use them:** For precise correction after normal key-based syncing, or when applying the same value to multiple selected items.

An end time before its start time is invalid and is highlighted as an error.

### Background Vocal

**What it does:** Marks a line as overlapping supporting or backing vocals rather than the main vocal line.

**Where:** **Edit → Line Properties → Background Vocal**, or right-click the line.

Use it only when the vocal genuinely overlaps another lyric line. Background-vocal structure and compatibility are explained in the TTML guide.

### Duet Vocal

**What it does:** Marks a line as the alternate singer/side in a duet layout.

**Where:** **Edit → Line Properties → Duet Vocal**, or right-click the line.

Use this for alternating performers, not merely because two people sing together. Check the result in Preview mode.

### Ignore Sync

**What it does:** Skips a selected line during the normal timing sequence.

**When to use it:** For content that must remain in the project but should not consume the next timing action. Remove the flag if the line actually needs timing.

**Where:** **Edit → Line Properties → Ignore Sync**.

### Empty Beat Count

**What it does:** Represents intentional spacing or beats associated with a word.

**When to use it:** Only for formats/rendering behavior that need explicit empty-beat information. It is not a substitute for fixing ordinary word timestamps.

**Where:** Select a word, then **Edit → Word Timing → Empty Beat Count**.

### Obscene

**What it does:** Marks a word as explicit so compatible players can mask it when their profanity filter is enabled.

**Where:** Select the word, then **Edit → Word Properties → Obscene**.

This does not change the lyric text. Preview mode has **Mask Obscene Words** to test the behavior.

### Translation and romanization

Each line can contain a translation and line romanization. Words can also contain individual romanized readings.

**Where:** Select content in Edit mode, then use **Secondary Content → Translation / Romanization** or **Word Properties → Word Romanization**. Display toggles are in **Auxiliary Line Display**.

The **Romanize** tool can generate Japanese romaji, Mandarin pinyin, Cantonese jyutping, or Korean romanization. It is useful as a draft, but rare kanji, names, stylized readings, and mixed-language lines require human review.

## Timing features

### Word Sync and Line Sync

**What they do:** Choose whether timing actions advance through individual word/syllable chips or whole lines.

**Where:** **Time → Sync Level**.

Use **Word Sync** for normal syncing. Use **Line Sync** for syncing a whole line first to then manually adjust timings in the spectrogram.

### Mark Begin, Commit, and Mark End

These are the core timing actions shown in the Time-mode hotkey cheatsheet:

* **Mark Begin** (`F`) sets the beginning of the current unit.
* **Commit** (`G`) finishes the current unit and advances continuously.
* **Mark End** (`H`) sets the ending boundary.

Navigation defaults include `A`/`D` for previous/next word, `W`/`S` for previous/next line, `R`/`Y` for moving and replaying nearby words, and `Home`/`End` for jumping to the first/last word and playing. All bindings can be changed in Preferences.

### Playback controls

The audio bar provides play/pause, seek, volume, and playback speed. Default keyboard controls are:

* `Space`: play or pause
* Left/Right Arrow: seek backward or forward 5 seconds
* Up/Down Arrow: change volume
* `[` / `]`: decrease or increase playback speed
* `'`: reset playback speed

Slower playback can help with dense vocals, but always review at normal speed.

### Time Offset and Commit Offset

**What they do:** Compensate for consistent input or playback delay while syncing.

**Where:** **Time → Timing Adjustment**. Persistent defaults and trigger behavior are under **Preferences → Editor & Sync**.

* **Time Offset** shifts recorded timestamps to compensate for overall latency.
* **Commit Offset** adjusts the commit/end input separately.
* **Commit Offset** in the ribbon applies the current adjustment to the project when you are satisfied.

Run **Tools → Audio/input latency test** before guessing large values. Offsets fix consistent delay; they do not fix an audio file that drifts relative to the original song.

### Smart first/last word and timestamp judgment

**Where:** **Preferences → Editor & Sync**.

* **Smart First Word** and **Smart Last Word** assist with line boundaries around the first and last timed words.
* **Sync Timestamp Judgment Mode** chooses whether the tool uses the first key-down, last key-up, their average, or legacy behavior.
* **Keybinding Trigger Timing** chooses whether commands fire on key-down or key-up.

Keep the defaults until you understand what timing error you are trying to correct.

### Sync to spectrogram cursor

**What it does:** Records the timing keys (`F`, `G`, `H`) at the spectrogram hover cursor position instead of the current audio playback time.

**When to use it:** When you want to place boundaries on a spot you can see in the spectrogram rather than where playback happens to be. It is off by default.

**Where:** **Preferences → Editor & Sync**.

### Auto-scroll, active line highlight, and locate

**What they do:** Keep the editor following the song while it plays.

* **Auto-scroll** scrolls the editor to keep the active lyric line centered during playback. It is opt-in and can be toggled from the ribbon or **Preferences → Editor & Sync**. The easing is smooth and tracks playback.
* **Focus Main Line During Playback** makes auto-scroll follow the main (v1) vocal and ignore background vocals unless no main vocal is active. It is greyed out while auto-scroll is off.
* Scrolling with the mouse wheel pauses auto-scroll for one second, then it eases back to the active line. It stays idle while playback is paused.
* **Active line highlight** marks the line currently being sung.
* **Locate active line** (`Ctrl+Shift+L` / `Cmd+Shift+L`) centers the active line on demand, even with auto-scroll off.

Switching between Edit, Time, and Preview keeps the same playback position and line in view.

### Word wrap in Time mode

**What it does:** Lets word cards in the Time tab wrap onto multiple lines instead of overflowing sideways.

**Where:** **Wrap Words in Time Mode** in the Time-mode Display Options ribbon or in **Preferences → Editor & Sync**. It is on by default.

### Technical timing overview

**What it does:** Shows a table of every line and word with its timestamps, alongside the editor.

* Clicking any syllable or word seeks to that word's timestamp and shows its active frame.
* The table auto-scrolls to follow playback.
* An **order toggle** switches between *chronological* order and *textual* (document) order. Textual order keeps unsynced lines where they sit in the lyrics instead of pushing them to the end.
* The header stays compact in narrow side panels, and the side preview remembers whether it was open.

### Manual timestamp editing and double-click editing

**What they do:** Let you type or adjust word timestamps directly in Time mode, and double-click synced words to edit their text inline.

**Where:** Enable **Time → Assistant Settings → Manual Timestamp Editing / Double-Click Word Editing**.

Use these for targeted repairs without switching back to Edit mode.

### Error highlighting

Highlight Errors highlights invalid timing.

**Where:** **Time → Display Options → Highlight Errors**.

Treat these as review aids. A visually clean editor can still sound wrong.

### Sync Line Timestamps

**What it does:** Recalculates line start/end boundaries from their timed words.

**When to use it:** After word timing is correct but the parent line timestamps are missing or stale.

**Where:** **Tools → Sync Line Timestamps**.

### Copy timings and Snap to playhead

* **Copy timings to…** copies the selected line's line and word timings onto another existing line. Use it for repeated phrases with the same rhythm.
* **Snap selected lines to playhead** moves the selected timing block so its beginning matches the current audio position while preserving relative timing.

These are available from line context menus or their keyboard action. Verify repeated phrases: the second performance is often slightly different.

### Time Shift

**What it does:** Moves timestamps earlier or later without changing their spacing.

**When to use it:** When a selection—or the entire song—is consistently early or late by the same amount.

**Where:** **Edit → Time Shift…**.

### Time Stretch

**What it does:** Scales all timestamps from an old duration to a new duration. It can read durations from audio files.

**When to use it:** When the same performance was uniformly speed-changed. Do not use it for an edit with inserted silence, dialogue, or independently changed sections.

**Where:** **Edit → Time Stretch…**.

## Spectrogram and detailed audio inspection

### Line spectrogram

**What it does:** Opens a detailed frequency view around a lyric line. You can inspect transients, audition the selection and nearby audio, and apply timing adjustments visually.

**When to use it:** For consonants, breaths, quiet syllables, dense mixes, or boundaries that are difficult to hear from normal playback.

**Where:** Open the spectrogram action for a line. Spectrogram appearance is configured under **Preferences → Spectrogram**.

Default audition keys are `Q` for 500 ms before, `S` for the selection, and `W` for 500 ms after while the spectrogram is active.

The spectrogram is evidence, not an automatic answer: visible instrumental transients may not match the vocal boundary.

### Audio equalizer and MP3 conversion

**Where:** **Preferences → Audio**.

* The equalizer can emphasize or reduce frequency ranges and supports presets. Use it to make vocals or consonants easier to hear; it does not alter exported TTML.
* MP3 conversion settings control the built-in conversion path used to reduce decoding/timing drift on problematic MP3 files.

## Metadata

### Metadata editor

**What it does:** Adds or edits TTML metadata such as song identity and credits.

**Where:** **Edit → Edit lyrics metadata…**.

Use the standard fields for recognized metadata and custom keys only when a target format or service explicitly requires them. Credits should identify the people responsible for the lyric work, not the performing artists unless they also did that work.

## Preview and final checking

Open **Preview** mode after timing. The renderer modes are diagnostic views, not export formats:

* **Standard:** general lyric preview.
* **Toxi:** tests the Toxi lyrics engine and its animation behavior.
* **Spicy:** tests the Spicy Lyrics renderer, including karaoke and line-based layouts.  This is the recommended default.
* **Timing:** emphasizes timing rather than presentation.
* **AMLL:** deprecated in this build; use Standard unless testing old behavior specifically.

Common Preview controls include:

* show or hide translations and romanization;
* mask words marked Obscene;
* adjust word fade width and instant fade-out;
* in Spicy mode, switch Simple Lyrics, force line rendering, and choose animated, color, or static backgrounds;
* under Advanced, toggle V-Sync and the FPS counter for renderer troubleshooting.

Preview with the exact original audio before submitting. If you synced against an isolated vocal stem, the final check against the original mix is mandatory.

## Checklist, grammar, and review tools

### TTML Checklist

**What it does:** Maintains a local queue of songs, notes, progress, and completed items.

**When to use it:** To track work across multiple songs. It does not validate the currently open TTML.

**Where:** **Tools → TTML Checklist**.

### Urban Dictionary lookup

**What it does:** Looks up selected slang without leaving the editor.

**Where:** Use the configured Edit/Time keybinding (`F` in Edit mode and `Shift+F` in Time mode by default).

Definitions are community-written and may be inaccurate or explicit. Use the feature for context, not as an authoritative transcription source.

## Exporting to other formats

**File → Export lyrics** can convert the current project to supported formats including LRC, enhanced LRC, QRC, YRC, Lyricify Syllable, and ASS subtitles.

Use TTML as the master copy. Other formats may not preserve all TTML features, especially overlapping background vocals, translations, romanization, metadata, or exact millisecond structure.

## Preferences and customization

Open **Edit → Preferences**. The **search field** at the top filters the categories as you type, opens the best match, and highlights the closest setting. Use it when you cannot remember which tab holds something.

* **General:** interface language, simple/advanced layout, compact background vocals, and desktop privacy/integration options.
* **Editor & Sync:** timestamp judgment, key trigger timing, latency offsets, smart boundary behavior, and pre-highlight timing cues.
* **Files & Storage:** import normalization, special background-vocal compatibility, folder projects, auto-save interval, and history retention.
* **Audio:** volume, playback speed, equalizer, presets, and MP3 conversion behavior.
* **Keybindings:** view and replace every shortcut. Conflicts should be resolved before timing.
* **Appearance:** themes, fonts, backgrounds, gradients, editor colors, spacing, and saved presets. These change the editor, not the exported TTML.
* **Spectrogram:** palette and custom gradient stops.
* **Backup:** export or restore selected settings, keybindings, appearance assets, projects/history, and plugins.
* **AI:** optional AI judging sidebar just for fun.
* **Developer:** diagnostics and experimental controls intended for troubleshooting, not normal lyric creation.

### Backup and restore

**What it does:** Creates a portable backup containing whichever categories you select: settings, keybindings, appearance assets, projects/history, and plugins.

**When to use it:** Before clearing browser data, moving devices, reinstalling, or making large preference changes.

Before exporting, an expandable **contents preview** shows category counts, the items in each category, and the estimated file size. The **Assets** category includes appearance presets and the custom font. API keys (Genius and AI sidebar) live in their own opt-in **API keys** category, off by default and never bundled with Settings. The last workspace folder and recent project paths are not exported, because they only make sense on the original device.

Restoring replaces the selected local data and reloads the app. Keep the backup file somewhere outside the browser's storage.

## Plugins and optional integrations

### Community plugins

The plugin manager can install community-made WASM importers, exporters, and tools. Installed tools may appear in the Tools menu.

Plugins extend the editor and are not required for standard TTML work. Only install plugins you trust, and do not assume another reviewer has the same plugin available.

### Discord Rich Presence and PreMiD

Optional presence integrations can show the current project, editor mode, progress, playback state, and elapsed editing time. They do not change the TTML.

Use them only if you are comfortable sharing that activity. Desktop Discord presence and website PreMiD support depend on platform and configuration.

### Guided Beginner Workflow

**What it does:** Walks through audio import, lyric review, timing, credits, export, and local testing while you work on your own song. The panel can be moved, collapsed, or reopened later.

**Where:** **Help → Start Guide**.

This is the best starting point for a first TTML. This feature reference is the companion for everything the guided workflow does not explain.

## Useful default shortcuts

Shortcuts can be changed under **Preferences → Keybindings**, so the app's displayed binding is always authoritative.

| Action | Windows/Linux | macOS |
|--------|---------------|-------|
| New / Open / Save | `Ctrl+N` / `Ctrl+O` / `Ctrl+S` | `Cmd+N` / `Cmd+O` / `Cmd+S` |
| Undo / Redo | `Ctrl+Z` / `Ctrl+Shift+Z` | `Cmd+Z` / `Cmd+Shift+Z` |
| Edit / Time / Preview mode | `Shift+1` / `Shift+2` / `Shift+3` | Same  |
| Play or pause | `Space`       | Same  |
| Previous / next word | `A` / `D`     | Same  |
| Previous / next line | `W` / `S`     | Same  |
| Mark Begin / Commit / Mark End | `F` / `G` / `H` | Same  |
| Seek backward / forward | Left / Right Arrow | Same  |
| Slower / faster / reset speed | `[` / `]` / `'` | Same  |
| Auto Segment | `E`           | Same  |
| Duplicate at current time | `Ctrl+L`      | `Cmd+L` |

## A practical rule for choosing features

Use the simplest feature that solves the problem:


1. Prepare accurate words and sensible syllable chips in **Edit**.
2. Time them by ear in **Time**.
3. Use offsets, direct timestamp editing, or the spectrogram only for a specific problem you can identify.
4. Check structure and metadata.
5. Review the entire song in **Preview** with the original audio.
6. Save TTML as the master file, then make any secondary exports.

More controls do not automatically produce better syncing. Accurate listening and a complete final review matter more than using every tool.