Skip to content

Summary for song lifetime #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
emuell merged 2 commits into from
Sep 23, 2026
Merged

Summary for song lifetime #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
15e3f53
add summary for song lifetime
unlessgames Sep 23, 2026
e5a44ea
add link to tool.md
unlessgames Sep 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion docs/guide/song.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -397,4 +397,29 @@ local selected_device = song.selected_track_device
if selected_device then
print("Selected device: " .. selected_device.display_name)
end
```
```

## Lifetime of a Song

Below is a timeline of the different events that happen regarding songs while Renoise is running with your tool enabled. Tools that want to keep some context around based on the current song will want to manage it by listening to some or all of the listed observables for changes.

### Initialization

1. Renoise boots up
2. Your tool's `main.lua` is executed
3. Two things happen without a strict order
* A `Song` is loaded and [`app_new_document`](../API/renoise/renoise.ScriptingTool.md#app_new_document_observable--renoisedocumentobservable) fires
* The user's saved preferences are loaded for your `Tool` and [`tool_finished_loading`](../API/renoise/renoise.ScriptingTool.md#tool_finished_loading_observable) fires

### User loads a new song

1. If the user saves the previous song (`A`) before loading a new song (`B`) these save related notifier trigger
1. [`app_will_save_document`](../API/renoise/renoise.ScriptingTool.md#app_will_save_document_observable) fires with song `A`
2. [`app_saved_document`](../API/renoise/renoise.ScriptingTool.md#app_saved_document_observable) fires with song `A` (if saving was successful)
2. [`app_release_document`](../API/renoise/renoise.ScriptingTool.md#app_release_document_observable) fires with song `A`
3. [`app_new_document`](../API/renoise/renoise.ScriptingTool.md#app_new_document_observable) fires with song `B`

### User quits Renoise

1. Step 1 and 2 happens from above (1 only if the song was saved)
2. [`tool_will_unload`](../API/renoise/renoise.ScriptingTool.md#tool_will_unload_observable) fires
2 changes: 2 additions & 0 deletions docs/guide/tool.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -370,6 +370,8 @@ Some important notifiers include:
* `app_will_save_document_observable` Fired just before the song is saved.
* `app_idle_observable`: Fired periodically, useful for low-priority background tasks.

See a detailed timeline for these notifiers in [Lifetime of a Song](./song.md#lifetime-of-a-song)

## Preferences

Tools can have preferences that are saved and loaded by Renoise. To use them, we first need to create a [`renoise.Document`](../API/renoise/renoise.Document.md) object which holds the options that we want to store.
Expand Down
Loading