Projects

A project is a folder ending in .marbble, holding project.json and an Audio Files/ folder (and Freeze Files/ once a track is frozen, Alternatives/ once it has project alternatives, and Backups/ once it has been saved twice). Projects from before Marbble was renamed end in .fermata; they open and save as they are.

The Project Chooser

Opens at launch (by default) and from File › New… (Ctrl+N) and File › Open Recent… (Ctrl+Shift+O).

• New Project: four templates:

  • Empty Project;
  • Record Audio: one audio track on input 1, record-enabled;
  • Software Instrument: one instrument track with Marbble Synth, record-enabled;
  • Songwriter: Vocals and Guitar audio tracks on inputs 1 and 2, plus a Keys instrument track, all record-enabled.

  Set the name, location (default ~/Music/Marbble, or Settings › General › Project Folder), tempo (20 to 400 BPM), time signature and key. Double-click a template to create it at once.

• My Templates: the templates you saved, below the built-in ones (see Project templates). Right-click one to Rename… or Delete it.

• Recent: the last 20 projects you saved or opened, with track count, tempo and how long ago each was saved. Missing projects are marked and can be removed from the list (×).

• Open…: choose any .marbble folder.

• Show at launch: untick it to start straight into an empty project.

Open, save and close

• File › Open… (Ctrl+O): choose a .marbble folder. Save (Ctrl+S) and Save As… (Ctrl+Shift+S). Save As to a new folder copies the audio files that were in the old project folder.
• You’re asked before unsaved changes are discarded (when quitting, opening or creating another project), unless you turn that off in Settings › General. Don’t Save also deletes the autosave.
• A project whose sample rate differs from the audio device switches the device to the project’s rate when opened.
• You can open a project from the command line: marbble path/to/Song.marbble.
• File › Revert to Saved goes back to the last saved version, after asking (the changes since, and their autosave, are dropped).

Project templates

File › Save as Template… saves the project as a template of your own, as in Logic: its tracks, routing, plug-ins with their settings, tempo, time signature, key and project settings, without regions or audio. Saving under an existing template’s name asks before replacing it.

Your templates appear under My Templates in the Project Chooser, where a project made from one starts with all of that and no regions. Right-click a template there to Rename… or Delete it. Templates are files in the templates folder of the settings folder (~/.config/marbble/templates on Linux and macOS, %APPDATA%\marbble\templates on Windows), one <name>.json each.

Project alternatives

Like Logic, a project can hold several alternatives: versions of the arrangement (tracks, regions, mix, settings) in the same project folder, sharing its audio files. Try a different edit or mix without a copy of the whole project.

• File › Project Alternatives lists them, with the current one ticked; choose another to switch to it. Switching saves the current one first (with unsaved changes, it asks first).
• New Alternative… saves the current one, then carries on as a copy of it under the name you give (the project’s name is the first alternative’s name).
• Edit Alternatives… lists them to Switch (or double-click), Rename… or Delete…. Deleting the current one switches to another without saving it. A project keeps at least one alternative, and deleting one also deletes its backups. These can’t be undone.
• Opening the project opens the alternative you were last working on. Autosave, recovery and backups apply to the current alternative. A project never saved is saved first.
• Save As… saves just the current alternative into the new folder.

Backups and Revert to

Each save keeps the version it replaces as a backup, separately for each alternative, up to Settings › General › Backups (10 by default; 0 keeps only the last one, as project.json.bak). File › Revert to lists them by when they were saved (“Today 14:32”, “Yesterday 09:10”, then the date), newest first. Choosing one asks, then loads it; the project as it was (unsaved changes included) becomes a backup itself, so reverting to it undoes the revert.

Autosave and recovery

• While a project has unsaved changes, Marbble writes project.autosave.json into its folder every 2 minutes (Settings › General › Autosave: Off, or every 1, 2, 5, 10 or 15 minutes). It isn’t written while recording. Saving removes it.
• Every take is autosaved the moment you stop recording, as is the result of Bounce in Place, Freeze and importing audio files (Settings › General › After Recording, on by default; it works with the interval autosave off too). This writes the autosave, not your project: project.json only changes when you save, so Don’t Save still returns to the last saved version. Starting to record also autosaves unsaved changes, so new tracks are recoverable along with their takes.
• Crashes while recording: while you record, Marbble keeps each take’s file valid on disk every 2 seconds and keeps a small journal (recording-….journal.json) in the project folder. If Marbble crashes, is killed or the computer loses power mid-take, the audio recorded up to that moment is recovered: the file is repaired and the take goes back on its track where it was recorded (cycle recordings as a take folder). If the track itself was never saved, it is recreated. The journal goes away once the take is in the autosave or the project is saved.
• At launch, Marbble looks in the recent projects and the projects folder for autosaves newer than their project.json, and for interrupted recordings, and offers to Recover them (or Discard, or decide Later; projects you don’t recover are offered again next time). The sheet says which takes on which tracks were being recorded. Opening such a project asks the same. Recovering puts the takes back as one undo step (Undo: Recover Recording). Discarding keeps the recorded files in Audio Files, repaired, so you can still import them by hand.
• A recovered project counts as edited; save it to keep the changes.
• Damaged files: saves are written to a temporary file and then renamed into place, so a crash during a save leaves the previous version intact, and each save keeps the previous version as a backup (above). If project.json is missing, cut short or damaged when you open a project, Marbble opens the autosave instead, or failing that the newest backup, and says so; save to repair it. A damaged autosave isn’t offered for recovery.

Project Settings

File › Project Settings… (Alt+P, or the LCD’s chevron menu) holds what is saved with the project:

Tab	Settings
General	Tempo (5 to 990 BPM), Time Signature, Key, Sample Rate (with a warning when existing audio would play at the wrong speed).
Recording	Bit Depth: Use Settings, 24-bit integer or 32-bit float; Count-in on or off.
Metronome	The metronome settings (see Settings › Metronome).
Notes	Free-form notes (lyrics, session notes, who played what).

Tempo, time signature, key, bit depth, metronome settings and notes can be undone. The sample rate change is applied to the audio device and is not an undo step.