Backtracking
Back to the home page

Backtracking User Guide

Download from GitHub

Contents

Generated from docs/USER_GUIDE.md · 5fe9224 · · View on GitHub

繁體中文 · English · Installation and build · Hardware usage

Editing and background capture are separated in this update; see integration status and limits.

Choose what to capture

What you want to sampleWhich edition to use
A browser, media player, or another desktop appOpen the desktop recorder and choose system playback or the app in Options.
A microphone, or system playback plus a microphoneChoose a microphone in desktop Options or enable A/B to capture them separately.
One DAW track, a bus, or the master outputInsert the VST3 or CLAP plug-in on the relevant effects chain. It captures mono or stereo audio at that point and passes the input through unchanged.
A software instrument with effectsInsert Backtracking after the instrument and any effects you want in the sample. Move it ahead of those effects to capture the dry signal.

On Windows, route the source to the default playback device. If a DAW uses ASIO, exclusive mode, or another direct output path, use the plug-in to sample its track signal. On macOS, grant system audio recording permission when the desktop app first prompts you. Windows WASAPI · Apple Core Audio

Open settings

Click the gear in the toolbar or right-click inside the Backtracking window to open Options. The desktop app opens a separate window. VST3 and CLAP open Options inside the DAW's plug-in editor. The controls are grouped by category, including capture, theme accent, history length, auto-resume, transparency, WAV format, and folders. On desktop, you can also toggle Keep on top from the toolbar.

Choose a category on the left, then use the vertical settings list on the right. Larger bold titles, group headings, and body/control text of at least 15 distinguish hierarchy. History, auto-resume, transparency, and WAV format use dropdowns sized to their item count, up to ten rows before scrolling. Scroll the details pane for longer content. Desktop Options can be resized and keeps Close visible. The plug-in requests a larger editor and restores its prior size when closed.

Operating instructions live in this guide; the UI keeps controls, headings, labels, values, and necessary status/error/path information.

Keep quiet sections

Enable Keep quiet sections under Options → Capture (macOS label: 保留安靜片段). It defaults to Off, including older settings/projects without this field.

  • Off: existing silence compression omits long below-threshold gaps from the retained duration.
  • On: retain subsequent quiet input, digital zeros, and silence established by a known source clock. Quiet sections consume History and can displace older audio sooner.
  • Toggling changes future capture only. It preserves retained history, fixed editing material/aligned A/B ranges, and capture state. It neither retroactively compresses existing material nor restores discarded quiet audio.
  • Manual Pause, unavailable sources, and disconnected Senders retain their own behavior. Enabling the option does not invent unknown audio or DAW timing without a valid source/clock.

Windows handles eligible no-packet silence with periodic padding. With no callback on macOS, a real subsequent timestamp is needed to establish the interval; immediate trailing padding is not promised. Platform validation is tracked in the current plan, separately from older benchmarks. Desktop preferences and individual plug-in instances store the option.

In the macOS desktop app, use a mouse right-click or the trackpad's secondary click to open the menu. Use Control with a click and drag over the waveform to select audio.

The settings menu offers five background transparency levels. Choose 0%, 25%, 50%, 75%, or 100%, where 0% is opaque and 100% is clear. On the desktop apps, you can open Settings and adjust the value even at 100%. In VST3 and CLAP, Panel transparency fades the waveform panel's fill. The DAW provides the background behind it.

Sources, waveforms, and flags

  • Choose system playback, a microphone, or a specific app in desktop Options. App capture requires Windows OS build 20348 or later. On macOS, grant the relevant system audio or microphone permission when prompted.
  • The source list updates each time you open the drop-down. Windows lists apps with an open playback stream, including paused streams. macOS lists apps that Core Audio identifies as playback sources. If an app is missing, play some audio in it and reopen the list. Microphone entries come from the input devices the system currently makes available.
  • Enable A and B to capture two routes. For each, choose a source and Left, Right, Center, Mid, Side, or Merged. Merged uses the source's mono or stereo output format. Center requires a native center channel.
  • On Windows, A/B routes from the same source, such as System Side and System Mid, use the device's native sample rate. Export converts the whole selection if the WAV rate differs. Capture also smooths the splice when you resume after a pause.
  • For one source, choose a merged waveform or two L/R rows. With A/B enabled, A and B each use half the waveform area and have independent meters.
  • Flags mark range boundaries. Shift-drag directly creates a snapped selection; Ctrl on Windows / Option on macOS keeps free selection, with optional Shift for snapping. Targets prioritize visible flags, then painted bars, then painted seconds; the moving handle excludes itself. Only painted targets are eligible. Fully transparent backgrounds hide guides but retain interactive flags.
  • Selecting, adjusting flags, zooming, or panning fixes the original editing material/view while background capture continues. The selected samples and aligned A/B boundaries survive live rollover or a shorter history limit. Finishing/canceling returns to live view without changing manual Pause.
  • Waveform bins, strokes, and guide density adapt to the actual audio rectangle, visible duration, and interaction state.
  • Wider views use a continuous filled min/max envelope and outline; close views connect the original samples with a polyline. The width-based zoom limit allows about four logical pixels per sample. Resizing preserves the view; subsequent zooming follows valid limits. Drawing does not change selected or exported samples; see the current-round record for validation status.
  • Save snapshot, the global snapshot shortcut, and accepted drops export both tracks with the same boundaries and sample rate. If your DAW prompts for placement, choose separate tracks at the same start position.

Desktop update settings

Show waveform only

Turn on Show waveform only to shrink the native Windows/macOS desktop window to the waveform panel plus its visible border and disable the native shadow. Background transparency still follows Options: opaque, translucent, or fully transparent. Waveforms and flags remain visible and interactive at 100% transparency. Plug-ins can request a smaller editor; the DAW manages its outer frame, shadow, and background. This setting defaults to Off and is saved with the desktop preferences or the plug-in's DAW project settings.

Right-click the waveform to open Options. Choose Play (開始錄音 in the macOS app) when capture is paused, or Pause (暫停錄音) when capture is armed or recording.

When you switch modes, the desktop window fits the waveform panel's existing height and removes excess transparent space above and below it. Drag either inside side edge to adjust the width or the top and bottom edges to adjust the height. A narrower window shows the same retained duration over a shorter distance, reducing the number of pixels the waveform scrolls per second. The waveform shrinks to fit a shorter window. Turning the mode off restores the previous full-interface window size.

Desktop appWaveform-only minimum sizeFull interface minimum size
Windows240 × 48 logical pixels510 × 132 logical pixels
macOS240 × 48 points560 × 100 points

To restore the full interface, right-click the waveform and turn off Show waveform only. Windows/macOS native shadows are disabled in this mode; the optional thin border is controlled separately in Appearance Options.

Move and resize the desktop window

The Windows and macOS desktop apps use a frameless window. The gestures below move and resize it without automatic snapping near screen edges. The DAW manages the outer window for VST3 and CLAP. To close the desktop app, choose Quit from Settings.

With Keep on top enabled on Windows, Backtracking reasserts its position when the taskbar or another window on the same desktop covers it, while leaving input focus where it is. Windows manages the secure desktop and protected system surfaces.

Use the Windows system tray icon to show or hide the window. Capture can continue while the window is hidden. Choose Quit from the tray or Settings to exit. Place Backtracking.exe in a permanent location and enable Start with Windows to open Backtracking at its last window position when you sign in.

On macOS, use the menu bar item to show, hide, or quit Backtracking, or enable launch at login. If macOS asks for approval, allow the Backtracking login item in System Settings.

ActionWindows desktopmacOS desktop
Move the windowHold Alt and left-drag inside the content area.Hold Option and left-drag outside the waveform. Hold Command + Option and left-drag from anywhere in the content area.
Resize the windowMove the pointer to an inside edge or corner, then left-drag.Move the pointer to an inside edge or corner, then left-drag.
Select audioCtrl-left-drag for free selection or Shift-left-drag for snapping; combine both if desired.Option/Control-left-drag for free selection or Shift-left-drag for snapping; adding Shift also snaps.

Read the waveform and capture status

In the full interface, the toolbar's Play/Pause icon shows the available action: Start capture or Pause capture.

  • Waiting for sound. Armed capture waits for the silence threshold when Keep quiet sections is Off. With it On, known silence from a valid source can be retained; unavailable sources are handled separately.
  • Recording. The red indicator blinks. The newest audio appears on the right. Once the buffer fills, new audio gradually replaces the oldest samples.
  • Paused. Pause stops background capture and skips incoming audio. Play and existing auto-resume control capture separately; manual Pause remains at the zero-second setting. Selection, flags, zoom, and export preparation fix the editing view without implicitly pausing or forcing capture to resume.
  • Capture unavailable. If the desktop recorder loses its connection, press Play to retry.

History / Buffer offers 10/20/30/60 seconds or 3/5/10 minutes and defaults to 20 seconds. With default silence compression, two five-second sounds a minute apart join with only a short gap; Keep quiet sections also counts known silence against History. Very quiet input may fall below the default gate. Shortening trims the oldest live audio; lengthening gives future audio more room. Fixed editing material is not recut.

Live audio meter

The meter next to the gear reads the incoming audio signal and defaults to dBFS. Choose the unit in the gear menu. In the macOS desktop app, you can also click the readout to switch units. The meter displays — while paused or when a reading is unavailable.

ModeWhat it shows
dBFSDigital sample peak level. 0 dBFS is digital full scale.
VUA 300-millisecond RMS estimate of average level. A 1 kHz sine wave with a −18 dBFS peak reads 0 VU.
LUFSMomentary loudness estimated with K-weighting and a 400-millisecond sliding window.

Loudness measurement references. ITU-R BS.1770 · EBU Tech 3341

Select and drag out

In the full interface, hover over an unselected waveform to preview all retained audio. Drag from anywhere on the waveform outside Backtracking onto a WAV target to export that range. For example, a full 20-second buffer exports 20 seconds; if only 7 seconds have been captured, the WAV is 7 seconds long. Both display modes invert the waveform-line color inside free or Shift-snapped selections. The selected range is used for export.

ActionWindowsmacOSResult
Enter selection modeHold Ctrl for free selection or Shift for snappingHold Option for free selection or Shift for snappingAdding Shift to Ctrl/Option also snaps.
Drop a clip into a DAWHold the primary mouse button on the waveform and drag outHold the primary mouse button on the waveform and drag outOnce ready, drop the WAV onto the REAPER timeline, FL Studio Playlist, or another WAV drop target.
Choose both endsHold Ctrl or Shift and left-dragHold Option or Shift and left-dragRelease to keep fixed material/selection while capture keeps its state; release modifiers to drag out the range.

Clicking, selecting, and dragging within the window only affect the waveform. To export a selected clip, drag it out and drop it on a target that accepts WAV files, or choose Save snapshot in Options. Canceled or rejected drops, including drops back in the source window, leave no export file. Keep the mouse button held while an export finishes preparing. If the DAW rejects the drop, choose Save snapshot in Options and import the WAV from the saved snapshots folder.

With Backtracking focused, press Esc or Backspace to cancel editing and return to live view without writing a file. Background capture keeps its prior state; a manual Pause is not cleared.

Save a snapshot

Choose Save snapshot in Options to save from the current recorder. A selection uses its original fixed samples with the same A/B sample boundaries. With no selection, it saves all audio retained when triggered. Saving neither implicitly pauses capture nor forces manual Pause to resume. Selected-range completion can return to live view; completion of a background full-history save does not cancel a selection created afterward.

On Windows, press Alt plus the physical key to the left of 1 (the ~ / grave key, without Shift). On macOS, press Fn/Globe plus that same physical key. The global shortcut works from the background, without focusing Backtracking or the plug-in editor. On Linux, use the snapshot shortcut helper. Options can select one plug-in instance as the global shortcut target. Backtracking does not bind Ctrl+S; it remains available to save the DAW project.

Arm, pause, and auto-resume capture

Choose Play to arm capture or Pause to pause it manually. Use the toolbar in the full interface or right-click to open Options in waveform-only mode. Play preserves fixed editing material/selection; canceling, an ordinary click, or export completion returns to live view. Once re-armed, the next sound appends to live history within the limit.

Auto-resume retains 0/5/10 seconds and its 10-second default. Editing fixes material/view without implicitly pausing capture. Canceling, an ordinary waveform click, or export completion returns live without forcing manual Pause to resume. Play and existing auto-resume control capture separately: manual Pause remains at zero seconds; 5/10 seconds retain their timer rules. Keep quiet sections determines whether quiet/zero input is retained while armed.

Existing Off, 20-second, and 30-second settings use the 10-second default.

Clear the current recording

Click the trash icon in the toolbar. It is labeled Clear capture on Windows desktop and Clear captured audio in the plug-ins. This empties the waveform, selection, and audio held in memory. If capture is armed, incoming sound starts filling the waveform again. You can find previously exported WAVs in the save folder.

Output location and file format

You can choose and open both folders from Options. Successful drops use the default export folder. The global snapshot shortcut and Save snapshot use the saved snapshots folder. Existing export destinations are carried forward.

EditionDefault export folderDefault saved snapshots folder
macOS desktop~/Backtracking/output/~/Backtracking/saved/
Windows desktop%USERPROFILE%\Backtracking\output\%USERPROFILE%\Backtracking\saved\
VST3 / CLAPBacktracking/output/ in your home directoryBacktracking/saved/ in your home directory

Choose the sample rate and encoding independently in the gear menu.

EditionSample rate menuEncoding menu
Windows desktopWAV rateWAV encoding
macOS desktopWAV 匯出格式 → 取樣率WAV 匯出格式 → 編碼
VST3 / CLAPWAV sample rateWAV sample format
WAV settingOptionsDefault
Sample rate44.1 kHz, 48 kHz, 96 kHz48 kHz
Encoding16-bit PCM, 24-bit PCM, 32-bit IEEE float32-bit float

Snapshot saves and drag-and-drop exports use the current WAV settings. Any sample rate conversion happens during export. On desktop, Left and Right export as stereo with audio on the corresponding side, Side exports as stereo with an inverted right channel, and Mid and Center export as mono. Merged and the plug-ins use the captured channel count.

Enable Export every file as mono to export each WAV in mono. Stereo Merged and stereo plug-in captures average the left and right channels. Side exports the captured Side signal. A and B still export as individual files. The option defaults to Off. The rolling history lives in memory, so export any clips you need before closing the app or removing the plug-in.

Save and restore settings

The Windows and macOS desktop apps save your history length, auto-resume delay, theme accent, background transparency, meter mode, WAV export settings, both folders, keep-on-top setting, and waveform-only mode as you change them. Those preferences are restored the next time you open the app.

  • Windows. Settings are stored in %LOCALAPPDATA%\Backtracking\Settings, with %APPDATA%\Backtracking\Settings as a fallback when LOCALAPPDATA is unavailable. The app restores its previous window position.
  • macOS. Settings are stored in the macOS user preferences. The app also restores the desktop window's size and position.

For VST3 and CLAP, the DAW project stores each plug-in instance's history length, auto-resume delay, theme accent, panel transparency, meter mode, WAV export settings, both folders, and waveform-only mode. Save the project manually after making changes. When you reopen that project, the DAW restores each instance's settings.

Troubleshooting

SymptomWhat to check
Audio plays but the waveform stays stillDistinguish a fixed editing view from paused capture: cancel editing to return live, or use Play after manual Pause. On Windows, verify the default playback source. On macOS, check audio permission. In a DAW, check playback/monitoring and the signal at the insert.
Capture stops after switching Windows playback devicesSet the new device as the default playback device, then press Play to reconnect.
The plug-in does not appear in the DAWVerify that the entire .vst3 or .clap is in a scanned folder and that its architecture matches the DAW. Rescan using the steps below.
The DAW refuses the dropDrag outside the window, keep the mouse button held while the WAV prepares, and release on an audio timeline or Playlist. You can also choose Save snapshot in Options and import the WAV from the saved snapshots folder.
The WAV could not be writtenCheck that the waveform contains audio and choose a writable save folder.

Offline rendering. CLAP skips capture when the host reports offline mode. The nice-plug 0.4.2 VST3 wrapper can pass the previous processing mode to Backtracking, so an offline render may enter the capture history. Export important clips before rendering. To stop capture for the entire render, set auto-resume to 0 seconds, then press Pause, avoiding the 5/10-second timer. A fixed editing view alone does not stop recording.

Installation and build

Run the commands below from the project root. Use Rust 1.95 or a newer stable version.

sh
git clone https://github.com/kekekewww/Backtracking.git
cd Backtracking

Windows desktop

Use Windows Setup to install the desktop app, select VST3/CLAP independently, and choose a separate scan-root folder for each format. Defaults are per user; add your chosen plug-in roots to the DAW's scan paths. Uninstall preserves recordings and settings. Setup path selection, build, and installation instructions

Requires Windows 10 or 11 x64, Visual Studio C++ Build Tools, and the Windows SDK. Run these commands in PowerShell.

powershell
cargo build --manifest-path desktop/windows/Cargo.toml --release --locked
.\desktop\windows\target\release\Backtracking.exe

macOS desktop

Requires macOS 14.2 or later and Xcode Command Line Tools. Open the built .app in Finder or use the open command below. Grant system audio recording permission on first launch. If you previously declined, check System Settings → Privacy & Security and try again. Apple Core Audio

sh
bash desktop/macos/build.sh
open target/bundled/Backtracking.app

VST3 and CLAP plug-ins

On Windows, use Visual Studio C++ Build Tools and the Windows SDK. On macOS, use Xcode Command Line Tools. Build for the architecture your DAW uses.

Windows PowerShell

powershell
cargo install cargo-nice-plug --locked
$env:CARGO_TARGET_DIR = Join-Path (Get-Location) target
cargo nice-plug bundle backtracking-plugin --release --locked --manifest-path plugins/backtracking-plugin/Cargo.toml

macOS Terminal

sh
cargo install cargo-nice-plug --locked
bash plugins/backtracking-plugin/bundle-macos.sh

Copy the complete .vst3 or .clap from target/bundled/ into a folder scanned by your DAW.

SystemVST3CLAP
Windows%CommonProgramFiles%\VST3\%CommonProgramFiles%\CLAP\
macOS/Library/Audio/Plug-Ins/VST3//Library/Audio/Plug-Ins/CLAP/

For a per-user macOS install, use the corresponding VST3 or CLAP subfolder under ~/Library/Audio/Plug-Ins/ and verify that your DAW scans it. Steinberg VST3 locations

  1. REAPER. Open Preferences. Under Plug-ins, check the path on the VST or LV2/CLAP page and rescan. Open FX on the target track and search for Backtracking. REAPER User Guide
  2. FL Studio. Open Options → File settings → Manage plugins. Run Find installed plugins with Verify plugins enabled. Add Backtracking to an effect slot on the target Mixer insert. FL Studio manual

Check the installation

  1. With Keep quiet sections Off, play two short sounds separated by silence and check default compression. Turn it On and repeat with a valid source and History longer than the full interval; known silence should remain. Toggling must not clear history/fixed selections or change manual Pause.
  2. At 0-second auto-resume, play audio and check the red indicator. Press Pause and verify capture stops; canceling must not clear manual Pause. Press Play, then test free selection, Shift-snapped selection, flags, and zoom while background capture continues. Repeat at 5/10 seconds, checking existing auto-resume separately. Canceling editing should return to the latest recording.
  3. Choose an export folder and set the WAV format to 44.1 kHz, 24-bit PCM. Click the waveform, select a range, drag inside the window, and drop outside on an invalid target. Verify that none leave a new WAV in the export folder. Then drag a selected clip into your DAW and check that one new WAV uses the chosen format. For plug-in use, try a VST3 instance and a CLAP instance.
  4. Change a preference and relaunch the desktop app to check that it is restored. For the plug-in, change a setting, save the DAW project, and reopen it to check the saved value.
  5. Turn on Show waveform only and check that the desktop window fits the waveform panel's prior height. Test 0%/50%/100% background transparency; waveforms and flags should stay visible and interactive when fully transparent. Right-click to open Options and test pausing and arming capture. Check that selecting a range changes its waveform color. On desktop, move the window near a screen edge and check that it stays where you release it, then resize it to the minimum size and restore the full interface and its prior size from Options.
  6. Set history to 60 seconds and change the theme color. Select a range, let background capture roll past the limit, then shorten History. Original samples/A-B boundaries should still refer to fixed material. Test Esc and Backspace: both return to live view without a new WAV. At zero-second auto-resume, canceling must preserve manual Pause; Play should resume capture while keeping editing material/selection.
  7. Move the desktop window, hide it from the tray or menu bar, play audio, then show it and check the waveform. Quit and reopen the app to check that the position is restored. If you enabled launch at login, sign out and back in to verify it.
  8. Choose a saved snapshots folder. Save while recording and verify capture continues. Select a range and save again; verify the full snapshot/fixed clip with aligned A/B boundaries. Save at zero-second manual Pause and verify it is not forced to resume. Switch apps and verify background saving with Alt plus the physical key left of 1 (the ~ / grave key, without Shift) on Windows, or Fn/Globe plus that key on macOS. For plug-ins, verify only the selected target is saved; Ctrl+S in the DAW should not trigger a snapshot.

Back to the project README