> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightloop.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Songs
> Display synchronized lyric slides on your Apple TV — timed to a backing audio track, with full style control.
Songs require **Apple TV app version 1.1 or later**. Update the LightLoop app on your Apple TV before using this feature.
Songs are a purpose-built media type for displaying worship lyrics on screen. You create a song in LightLoop's web-based Song Editor, linking lyric slides to an audio track with precise timing markers. On the Apple TV, lyrics appear and transition automatically in sync with the music.
***
## How Songs work
A Song item contains:
* **Lyric slides** — one or more lines of text per slide (blank slides create intentional pauses for instrumentals)
* **Audio track** — the backing music file (optional) (MP3, M4A, AAC, or WAV)
* **Background** — an image or video that plays behind the lyrics (optional)
* **Markers** — timestamps that map each slide to a moment in the audio track (optional)
* **Style settings** — font, size, color, alignment, effects, and more (optional)
When the song plays on an Apple TV, the audio track plays from your device's cache while lyrics cross-dissolve in time with each marker.
***
## Creating a Song
1. In the **Media Library**, click the **+ Song** button (or select **Song** from the upload menu)
2. Give the song a name and click **Create**
3. The **Song Editor** opens automatically
\*Alternatively, click any Audio item card in your Media Library and click 'Convert to Song'
***
## Importing songs & charts
Drag a chord or lyric file straight into the **Media Library** (or onto a playlist) and LightLoop parses it — no copy-and-paste. Supported file types: **`.onsong`**, **`.chordpro`**, **`.cho`**, **`.crd`**, and **`.txt`** (plus ProPresenter `.pro`/`.probundle`). You can drop several at once.
### Files with chords → Song
If the file contains chords, it imports as a **Song** automatically:
* **ChordPro** (`[C]inline` chords), **OnSong** (including *chords-over-lyrics*, where a line of chords sits above the lyric), and **CCLI SongSelect** ChordPro exports are all understood.
* **Title** comes from the file's embedded title (`Title:` / `{title: …}`), falling back to the filename (a trailing `- Artist` is trimmed, so `Just That Good - Kristian Stanfill.txt` → "Just That Good").
* **Key** comes from the embedded key (`Key:`, `Original Key:`, `{key: …}` — `[A]` brackets are fine); if there's none, LightLoop detects it from the chords.
* Metadata you don't want on screen — CCLI number, copyright, tempo, capo, book, notes — is recognized and kept out of the lyrics.
* Section labels (`Verse 1`, `Chorus:`, `REPEAT CHORUS`, …) become [stage section headers](#chords), hidden from the audience.
Open the imported song to record [timing markers](#setting-timing-markers), attach audio, or tweak the [display key](#chords).
### Files without chords → choose Song or Sermon
If no chords are found, LightLoop asks how to import the text (this applies to the whole batch you dropped):
* **Song lyrics** — each blank-line-separated block becomes a lyric slide.
* **Sermon** — each block becomes a slide in a new [Sermon](/web-app/sermons). To mark a slide as scripture, put the reference in brackets on its own line and the verse text beneath it:
```text theme={null}
[John 3:16]
For God so loved the world, that he gave his only begotten Son…
```
The bracket fills the slide's reference; the text below is used as-is (nothing is fetched). Blocks without a bracket are plain text slides.
***
## The Song Editor
### Lyrics panel
Type or paste your lyrics into the lyrics field. Slides are separated by line breaks:
```text theme={null}
Amazing grace, how sweet the sound
That saved a wretch like me
I once was lost, but now am found
```
**Formatting rules:**
* A **single blank line** between two verses creates a new slide
* **Two consecutive blank lines** create a blank (silent) slide — the screen goes empty
* A **blank line at the start or end** creates a pause slide at the beginning or end of the song
### Audio track
Click the **Audio** slot to choose an audio file from your Media Library. The audio track is cached on the Apple TV for offline playback. Supported formats: MP3, M4A, AAC, WAV. If no audio track is selected, you can still manually control your lyrics.
### Background
Click the **Background** slot to choose an image or video from your Media Library. The background fills the screen behind the lyrics.
* **Images** display statically for the duration of the song
* **Videos** loop continuously
***
## Setting timing markers
Markers tell LightLoop exactly when each lyric slide should appear. You can set them in two ways.
### Record in real time
1. Click **▶ Preview** to open the full-screen preview
2. Press **Space** to begin playback of the audio track
3. Press **M** (or click **Mark**) at the moment you want each new slide to appear
4. When finished, close the preview — your markers are saved automatically
### Edit markers manually
After recording, click **Edit Markers** to open the Marker Editor. This gives you a visual waveform timeline with precise control.
**In the Marker Editor you can:**
* **Drag** any marker handle to reposition it
* **Click** a marker to select it and see its exact timestamp
* **Arrow keys** nudge a selected marker by ¹⁄₃₀ of a second per press (\~33 ms)
* **Zoom** in/out with the − and + buttons (5 levels, from overview to sample-level detail)
* **Space** to play/pause audio while watching markers
* **Clear All** to start fresh
Changes in the Marker Editor are non-destructive — click **Save Changes** to apply or **Cancel** to discard.
***
## Style settings
Open the **Style** accordion in the editor to customize how lyrics appear on screen.
| Setting | Options | Default |
| ----------------------- | --------------------- | --------------- |
| Font | Font Families | DM Sans |
| Size | 8–120 pt | 52 pt |
| Weight | Normal / Bold | Normal |
| Style | Normal / Italic | Normal |
| Case | Normal / ALL CAPS | Normal |
| Color | Color picker | White (#ffffff) |
| Alignment | Left / Center / Right | Center |
| Vertical align | Top / Center / Bottom | Center |
| Shadow opacity | 0–100% | 55% |
| Stroke width | 0–20 pt | 0 |
| Stroke color | Color picker | Black (#000000) |
| Text background color | Color picker | Black (#000000) |
| Text background opacity | 0–100% | 0% (off) |
| Slide transition | 0–2 s crossfade | 0.3 s |
**Text background** adds a colored panel behind the lyric text — useful for readability over busy backgrounds. Set opacity to 0 to disable it.
***
## Chords
Chords appear **only on stage and confidence displays** — the TV Wall **Stage Display** quadrant and the iOS Remote's **Stage Mode**. Your audience output (program screen, web preview, lower-thirds) always stays lyrics-only. Showing chords on stage requires the latest Apple TV and LightLoop Remote apps.
LightLoop songs support inline [ChordPro](https://www.chordpro.org/) chords. Write a chord in square brackets immediately before the syllable it falls on:
```text theme={null}
[G]Amazing [G/B]grace, how [C]sweet the [G]sound
That [Em]saved a [D]wretch like [G]me
```
As soon as LightLoop detects chords in your lyrics, the **Chords** controls appear in the **Style** panel.
### Pasting ChordPro or OnSong charts
You don't have to write chords by hand. **Paste a [ChordPro](https://www.chordpro.org/) or [OnSong](https://onsongapp.com/docs/features/formats/onsong/) chart** into the lyrics box and LightLoop converts it to its inline form automatically:
* **Chords over lyrics** — a line of chords sitting above the lyric line (the OnSong style) is merged into inline `[chords]` at the right positions. Inline `[C]` charts are kept as-is.
* **Section labels** — `Intro`, `Verse 1`, `Pre-Chorus 2`, `Chorus:`, `REPEAT CHORUS`, `Turnaround`, etc. (both bare and the OnSong colon form) are recognized as sections: hidden from the audience screen, shown as a dim cue on stage.
* **Metadata header** — `Key:`, `Tempo:`, `Title:`, `Artist:` and similar lines are read from the top of the chart. The `Key:` value seeds the song's key, the title fills in the song name (when empty), and the metadata lines are removed from the lyrics.
The conversion is lossless to re-paste — pasting an already-inline chart changes nothing.
### Showing chords on stage
* Turn on **Show chords on stage view** to render chords above the lyrics on stage displays.
* Pick a **Chord color** (default amber, `#FFD400`) so chords stand out from the lyric text.
The same lyrics — minus the chords — continue to display on the audience screen, so you only ever maintain one copy of the song.
### Original key & Display key
LightLoop reads your chords and **auto-detects the song's key**, shown as the **Original key**. It uses real music-theory scoring rather than guessing from the first chord — it weighs how well every chord fits each major and minor key and uses the **dominant (V) chord** to tell a key apart from its relative minor:
| Chords | Detected key |
| ------------- | ------------ |
| `Em C G D` | G |
| `Bm D A G Em` | D |
| `C F G Am` | C |
| `Am Dm E Am` | A minor |
If a detection is ever off, just pick the correct **Original key** from the dropdown to override it.
Set a **Display key** to transpose the chord chart. Every chord — roots, slash basses (`D/F#`), and whole-measure chord charts (`[|Ab / / / |]`) — shifts to the new key, with sensible sharp/flat spelling for the destination. The lyrics never change; only the chords move.
### Sync to Audio
When the song has an audio track assigned, a **Sync to Audio** toggle appears next to **Display key**:
* **On** — the chord Display key automatically follows the audio [transposition](#transposition). Transpose the track and the stage chart moves with it. (Display key is locked while synced.)
* **Off** — chords stay in whatever Display key you choose, independent of the audio. Use this when a player is reading in a different key — for example, capoing.
### What renders on stage
* Chords sit above the syllable they precede, in your chosen chord color.
* Whole-measure **chord charts** (e.g. `[|Ab / / / |]`) render as their own line, with no lyric beneath.
* The **"Next" preview** on stage displays shows the upcoming slide's first chord line — also transposed to your Display key.
***
## Transposition
Audio transposition runs on LightLoop's servers and works regardless of Apple TV app version. The **original audio file is always kept** — every transpose re-shifts from the original, and you can revert at any time.
LightLoop can change a song's key without re-recording: it pitch-shifts the attached audio track to a new key **while preserving the original tempo**.
### Automatic key detection
When you assign an audio track to a song, LightLoop **detects its musical key in the background** and stores it as the song's key — no action needed. This becomes the starting point ("from" key) for transposing.
### Transposing the audio
1. In the Song Editor, open the **Audio** card and click **Transpose**.
2. In the dialog, set the **From key** (pre-filled from the detected key — change it to correct a misdetection) and the **To key**. LightLoop shows the number of semitones it will shift.
3. Click **Transpose**. LightLoop pitch-shifts the track and attaches the result. Processing happens in the background; the Audio card shows the status and updates when it's ready.
The transposed track now plays everywhere the song plays — Apple TV, TV Wall, and previews.
### Reverting
The original audio is never overwritten. Click **Revert** on the Audio card to drop the transposed file and return to the original track.
### Keeping chords in step
If you also display [chords](#chords), turn on **Sync to Audio** in the Style panel so the chord chart's Display key follows every audio transposition automatically. Leave it off to transpose the audio while keeping the on-screen chords in their original (or a different) key.
***
## Instrumental (karaoke)
Instrumental generation runs on LightLoop's servers and works regardless of Apple TV app version. The **original audio is always kept** — turning the toggle off restores it.
LightLoop can remove the lead/backing vocals from a song's audio to create an **instrumental (karaoke)** track — useful for congregational singing, rehearsals, or "vocals out" moments.
### Turning it on and off
The Audio card has a single **Instrumental** switch:
* **On** — if no instrumental exists yet, LightLoop generates one (this takes about a minute and runs in the background — the switch shows the progress). When it's ready, the instrumental is **automatically used on your outputs**.
* **Off** — removes the instrumental and restores the original track with vocals.
That's the whole model: switch on for an instrumental, switch off for vocals. There's nothing else to manage.
### Where it plays
When the instrumental is on, it plays everywhere the song plays — Apple TV, TV Wall, and the preview pages (including the editor's full-screen Preview). Your lyric **timing markers are unaffected**, because the instrumental has the exact same timing as the original.
### Working with transposed audio
The instrumental is built from the song's **current** audio. So if you've [transposed](#transposition) the song, the instrumental is generated from the transposed track and comes out **in the new key**. If both are active, the instrumental is what plays on your outputs.
Because the instrumental is a snapshot of the audio at the time it was made, **changing the key afterward doesn't rebuild it automatically**. To refresh it after transposing (or after replacing the audio), toggle **Instrumental off, then on again** to regenerate from the current track.
***
## Adding a Song to a Playlist
From the Song Editor header, click **+ Add to Playlist** to open the playlist picker. Playlists are listed newest first. Search by name, then click any playlist to add the song immediately.
You can also add songs to playlists from the Media Library — click a Song card, then click **Edit Song** in the detail panel, or drag the card directly onto a playlist in the sidebar.
***
## Playback on Apple TV
Requires **Apple TV app version 1.1+**.
When a Song item plays on Apple TV:
* The **audio track (if assigned)** begins from the locally cached file
* The **background** image or video (if assigned) fills the screen. Videos loop continuously.
* **Lyrics** appear and cross-dissolve at each marker timestamp
* The song advances to the next playlist item when the audio track ends (or when **Auto-advance** is enabled on the playlist)
If no markers are set, all lyrics are displayed on the first slide with no automatic transitions.
If no audio track is linked, the song displays each slide for the playlist's configured **Duration** setting, advancing automatically like an image.
***
## Tips
Paste the chorus text each time it appears — LightLoop treats each occurrence as an independent slide with its own marker. If you want a chorus to display identically each time, just copy-paste the lyrics in the editor.
Check that markers have been recorded. Open **Edit Markers** to confirm marker count and positions. If there are no markers, lyrics stay on slide 1 for the full duration of the audio.
Yes. Select a video from your Media Library as the background. The video loops continuously behind the lyrics for the full duration of the song.
Yes — both the audio track and background media are cached to the Apple TV before playback. Once cached, no internet connection is needed during a service.
Without an audio track, the Apple TV treats each slide as a timed image, displaying it for the playlist's configured duration before advancing. If no duration is set "0" - you can manually control the slides with your Apple TV remote.
Slide order is determined entirely by the order lyrics appear in the text editor. Reorder slides by editing the lyrics text directly.