Basic navigation
Manage files, audio parameters, playback controls, and visual rendering variables in the primary workspace.
Create vs Edit Modes
Manage annotation workflow states to draw new boxes or modify existing bounds.
Create Mode
Used to construct new annotation bounding boxes on the time-frequency spectrogram grid.
- Drawing: Left-click and drag across the spectrogram canvas to select a duration and frequency range.
- Auto-Commit: Releasing the click (PointerUp) commits the annotation to the grid database.
- Species Check: You must choose a species in the search selector first. If none is selected, creation is blocked with an alert.
- Abort creation: Press Escape button or Right click on the spectrogram canvas to discard the active box and switch directly to Edit Mode.
Edit Mode
Used to select, translate, resize, and delete existing annotations.
- Selection: Click on an annotation box directly or check its row in the grid. Hold Ctrl to select multiple boxes.
- Resizing: Click on a box to highlight it and reveal handles on its edges and corners. Drag these handles to adjust bounds.
- Moving: Click inside a highlighted box and drag to translate it in time or frequency.
- Navigation: Use Tab / Shift+Tab to cycle and edit sequentially.
Species Selector
Search, prioritize, and assign species taxonomy metadata to annotations.
Annotation Tools
Tools for automating, bulk updating, and processing annotations.
Sound Editing Tools
Destructive editing tools for modifying the underlying audio and spectrogram data.
Annotation Grid
The interactive table below the spectrogram that displays all current annotations.
Keyboard Shortcuts
A centralized reference for all keyboard inputs, event listeners, and navigation mappings in Spectrolipi.
Playback & Timeline Navigation
| Shortcut Key | Description | Action Scope |
|---|---|---|
| Spacebar | Toggles audio playback (Play / Pause). | Global playback state |
| ← / → | Seeks the playhead backward or forward. Step size depends on zoom factors. | Global audio player |
| Shift + ← / → | Seeks backward or forward at double the normal step speed. | Global audio player |
| Ctrl / Cmd + ← / → | Instantly jumps the playhead to the start or end of the audio track. | Global audio player |
| Scroll Wheel Hover Y-Axis | Zooms in/out on the vertical frequency axis relative to pointer. | Y-Axis Scaling |
| Click & Drag Hover Y-Axis | Pans the viewable frequency range up or down. | Y-Axis Scaling |
| Right-Click Hover Y-Axis | Instantly resets the vertical zoom to show the full frequency range. | Y-Axis Scaling |
Annotation Creation & Edit Modes
| Shortcut Key | Description | Action Scope |
|---|---|---|
| Escape | Deselects all annotations, cancels active editing fields, and clears box highlights. | Edit Mode / Table View |
| Delete or D / d | Deletes all currently selected annotations from grid and spectrogram canvas. | Edit Mode / Table View |
| Tab | Saves the active edit box and jumps focus to the next box (chronological order). | Edit Mode navigation |
| Shift + Tab | Saves the active edit box and jumps focus to the previous box. | Edit Mode navigation |
| Right-Click | Toggles between Create mode & Edit mode. | Spectrogram Canvas |
Advanced Tools (Magic Wand, Stamp, Audio Cut)
| Shortcut Key | Description | Action Scope |
|---|---|---|
| Shift + Scroll Wheel | Adjusts algorithm sensitivity (1% to 99%) in real-time during Magic Wand sessions. | Magic Wand auto-detection |
| Escape Tool armed | Exits Magic Wand mode, Repeat Mode, or Spectral Stamp Mode safely. | Active Tool Session |
| Escape Selection active | Disarms the timeline slice selection (Cut) overlay. | Cut & Selection Overlay |
Q & A
Detailed answers and workflows for common questions and advanced features.
File Management & Setup
Q: How to load an audio file from my local computer?
A: Click the "Load Audio" button (Folder icon) on the main toolbar. This will open a standard file browser window. Select your supported audio file (.wav, .mp3) and click Open. If you have unsaved annotations, a warning will appear before replacing the current workspace.
Q: How to load an audio file directly from the Xeno-canto database?
A: Click the "Load from XC" button (Cloud download icon) on the toolbar. Enter a valid 6-digit Xeno-canto catalog ID number into the prompt, and Spectrolipi will automatically download and render the audio file without needing to visit the website.
Q: How to import an existing CSV annotation file into the current workspace?
A: Open the left hamburger menu and click "Upload Annotations", or use the local hamburger menu inside the Annotation Grid itself. Select your CSV file. Ensure the CSV matches the expected header format so Spectrolipi can correctly draw the boxes.
Q: How to save and download my current annotations to a CSV file?
A: Open the left hamburger menu and click "Save Annotations", or use the local hamburger menu inside the Annotation Grid. This will immediately compile all your current rows and download a `.csv` file to your computer's default downloads folder.
Basic Navigation & Playback
Q: How to play or pause the audio track?
A: You can click the Play/Pause button on the main toolbar, or simply press the Spacebar on your keyboard. You can also click directly on the red playhead timeline bar to start playback from a specific timestamp.
Q: How to quickly jump to the beginning or end of the audio track?
A: Press Ctrl + ← to instantly jump to the start of the audio file. Press Ctrl + → to jump to the very end.
Q: How to seek forward or backward through the timeline?
A: Use the ← and → arrow keys to step backward or forward through the audio timeline. Holding Shift while pressing the arrows will seek at double the speed.
Q: How to zoom in or out on the timeline (X-Axis)?
A: Use the "X" dropdown spinner on the main toolbar. Increasing the multiplier stretches the horizontal axis so you can see shorter windows of time in higher detail.
Q: How to zoom in or out on the vertical frequency scale (Y-Axis)?
A: You can use the "Y" dropdown spinner on the toolbar for gross adjustments, or simply hover your mouse over the vertical frequency axis numbers on the left and use your scroll wheel to smoothly zoom in or out. You can also click and drag the numbers up or down to pan the frequency view. Right-click the axis to instantly reset the zoom to show the full spectrum.
Q: How to turn on the Magnifier to inspect small details?
A: Open the left hamburger menu and select "Spectrolipi Settings" (the gear icon). Check the box for "Turn On Magnifier". A floating magnifying glass overlay will now follow your cursor across the spectrogram.
Visuals & Display Setup
Q: How to change the color scheme/palette of the spectrogram?
A: Use the "Color Scheme" dropdown on the main toolbar. Spectrolipi defaults to SpectroFlare, but you can choose from alternatives like Viridis, Magma, Grayscale, or Jet.
Q: How to adjust the brightness and contrast (Gain) of the spectrogram visuals?
A: Use the "Gain Control" slider on the main toolbar. Sliding it to the right increases the visual intensity of faint sounds. Note that this is purely a visual rendering change and does not affect the actual amplitude of the audio file itself.
Q: Which settings are available in Spectrolipi settings?
A: Open the left hamburger menu and click "Spectrolipi Settings". A configuration dialog will appear featuring:
• Annotation Mode: Toggle between "Time-Frequency (Boxes)" or "Temporal (Intervals)".
• Magic box pad (px): Padding for creating annotation box around the detecttion of acoustic energy.
• Repeat last sensitivity: Checkbox dictating whether the Magic Wand remembers sensitivity of last commnited box.
• Default species format: Select whether species selection toggle button and labels display "Common name" or "Scientific name" by default.
• Maximum Frequency (Y-Max): To set default Y axix zoom.
• FFT Size: To set default underlying resolution of the spectrogram bins.
• Turn on Smart list: Toggles a draggable list of species for quick access.
• Turn On Magnifier: Toggles the cursor tracking magnifying lens.
Annotation Creation & Modification
Q: How to switch between Create Mode and Edit Mode?
A: Right-click anywhere on the spectrogram canvas to instantly toggle between Create Mode (drawing new boxes) and Edit Mode (selecting and moving existing boxes).
Q: How to create a standard rectangular annotation box?
A: Ensure you are in Create Mode. Click and drag your mouse across the spectrogram to draw a bounding box around the acoustic event, then release.
Q: How to cancel creating a box if I change my mind halfway?
A: While dragging to draw a new box, simply press Right-Click or the Escape key to discard the box immediately and switch back to Edit Mode.
Q: How to edit the boundaries of an existing annotation box?
A: In Edit Mode, click the box you want to modify to select it. Then, hover over any of the four edges until your cursor changes, and click and drag the edge to resize it. You can also click the center of the box to drag and move the entire annotation.
Q: How to delete a specific annotation from the canvas?
A: Select the annotation in Edit Mode, then press the Delete key (or D). Alternatively, you can click the "Delete Selected" trash can icon in the Annotation Tools section. You can doubel click the trash icon in the annotation box as well.
Q: How to use the Magic Wand tool to automatically snap a box to a sound's bounds?
A: Click the Magic Wand button to arm it. Click near the target sound. The algorithm will automatically shrink-wrap the box to the exact frequency and time bounds based on the acoustic energy.
Q: How to adjust the sensitivity of the Magic Wand tool?
A: While the Magic Wand is armed, hold Shift and scroll your mouse wheel. A tooltip will appear showing the Breadth-First Search (BFS) threshold percentage. A higher percentage (e.g., 5%) captures more faint background noise, while a lower percentage (e.g., 80%) restricts the box to only the loudest peaks.
Q: How to rapidly create identical-sized annotations using Repeat Mode?
A: Click the "Repeat Annotation" button to arm the tool. A dotted annotation box of same size of last committed annotation starts moving with the mouse. Simply click on new areas of the spectrogram to instantly stamp copies of the original box's exact dimensions. Note: Horizontal snap guide (pink line) is available.
Q: How to automatically find and label similar sounds using the Run SCC (Cross-Correlation) tool?
A: Select one existing annotations to act as a template. Click "Run SCC". Tweak the settings in the form if required. The system will scan the entire audio track for similar acoustic patterns as per the 3 presents. Select any one preset to apply and generate new annotation boxes where matches are found.
Species & Taxonomy Management
Q: How to select a species to create annotation?
A: Press species toggle button for Scientific name or common name. In the Species Search box type the common or scientific name, and select the matching suggestion.
Q: How to upload a custom species list CSV?
A: Open the left hamburger menu and click "Manage Species List". Under the "Upload Custom CSV" section, choose your `.csv` file. It should contain standard taxonomy columns (e.g., common_name, scientific_name).
Q: How to export the current species list for backup?
A: Open "Manage Species List". Click the "Export List as CSV" button to download a spreadsheet, or click "Save JS file" to export the raw JavaScript array structure used by Spectrolipi.
Q: What is smart species list?
A: Ensure "Turn on Smart list" is checked in the Spectrolipi Settings. A floating, draggable "Smart List" will appear on screen, giving you one-click access to species you've applied recently (last 10) or if the sound file was loaded from XC, it contains the species list from that XC record.
Annotation Grid (Table Operations)
Q: How to select one, multiple, or all rows in the annotation grid?
A: Click the checkbox in the first column of any row to select it. To select all rows simultaneously, click the master checkbox located at the very top of that column in the table header.
Q: How to sort the grid by specific columns (like "Begin Time" or "Species")?
A: Click directly on the column header text (e.g., click "Begin Time (s)"). Click it again to toggle between Ascending and Descending order.
Q: How to resize or reorder the columns in the grid?
A: To resize, hover over the border between two column headers and drag horizontally. To reorder, click and hold a column header and drag it left or right to a new position.
Q: How to edit text notes directly inside the grid cells?
A: Double-click on any cell in the "Notes" column. An inline text editor will appear; type your notes and hit Enter to save. Use Tab to quickly jump to the next row's note cell.
Q: How to bulk update Species or Metadata tags for multiple selected rows?
A: Check the boxes for the target rows in the grid. To update Species, choose a species in the search box and click the "Update Species" list icon in the Annotation Tools. To update tags (Sex, Life Stage), click the "Update Tags" icon in the Annotation Tools to open the bulk tag editor.
Sound Editing (Destructive Tools)
Q: How to select a specific time span on the audio timeline?
A: Click the "Select Time Span" pointer icon under Sound Editing Tools. Click and drag horizontally across the spectrogram canvas to define a blue highlighted time block.
Q: How to cut and completely remove a section of audio?
A: First, create a time span selection. Then, click the "Cut Audio" scissors icon. The highlighted audio will be deleted entirely from memory, and the track will collapse to fill the gap.
Q: How to replace a section of audio with pure silence?
A: Create a time span selection and click the "Silence Audio" icon. In the dialog box, ensure the mode is set to "Replace" and click Apply. The selected area's volume will be set to zero, but the total length of the track will remain identical.
Q: How to insert new silence into the audio track to increase its total length?
A: Create a time span selection roughly where you want the silence inserted, and click the "Silence Audio" icon. Switch the mode to "Insert". Type in the duration in seconds (e.g., 2.5), and click Apply. The track length will increase.
Q: How to apply a High Pass or Low Pass filter to a specific audio section?
A: Create a time selection. Click the "Apply Filters" icon. In the dialog, select either High Pass or Low Pass, enter your cutoff frequency in Hz, and click Apply.
Q: How to normalize the volume (amplitude) of the audio?
A: You can normalize the whole file or a selected time span. Click the "Normalize" icon, enter a target peak decibel level (like -3dB), and click Apply.
Q: How to undo an audio edit (cut, silence, filter) if I made a mistake?
A: Click the "Undo Edit" (rotate-left) icon in the Sound Editing Tools panel. This safely reverts the underlying audio buffer back to its state immediately prior to your last destructive action.
Advanced AI & BirdNET Integration
Q: How to automatically detect and classify sounds using the BirdNET AI model?
A: Open the left hamburger menu and click "Run BirdNET Model". A dialog will appear with configuration options. It may take a few seconds to load the model. Select your parameters and click "Start Analysis" to process the audio through the AI model locally in your browser.
Q: How to instantly convert BirdNET predictions into annotation boxes on my spectrogram?
A: After running the analysis, you will see a list of detected species & unique species in the dialog. Select required species from the unique species list and click "Insert Annotations". The model's time-stamps will instantly become editable bounding boxes on your canvas.
Xeno-canto Integration
Q: How to configure my Xeno-canto API key?
A: Open the left hamburger menu and click "Upload to Xeno-Canto". In the upload form, locate the "API Key" field at the bottom. You must copy and paste your personal API key directly from the "Your Account" page on the Xeno-canto website to authenticate.
Q: How to upload my annotations directly to Xeno-canto?
A: Ensure you have assigned species to your annotations. Click "Upload to Xeno-Canto" in the hamburger menu. Fill out the comprehensive form. Note: Xeno-canto file no is Mandatory. Provide your API key. Select Direct Upload with API and click Priceed.
Q: How to export a Xeno-canto compliant JSON file without uploading?
A: In the "Upload to Xeno-Canto" form, fill out all your metadata fields, but instead of selecting Direct Upload with API, select "Export JSON". This generates the exact formatted json file that Xeno-canto expects, gets saved it locally in downloads folder. You can then manually upload to Xeno-canto.
Q: How to combine multiple local annotation files into a single Xeno-canto dataset?
A: Open the hamburger menu and select "Create Xeno-canto Set". A dashboard will open allowing you to upload multiple local audio files along with their respective CSV annotations. You can define global metadata (like location) for the entire batch and package them together for upload.
Q: How do I view all my past uploaded Xeno-Canto recordings?
A: Open the left Hamburger menu and click "Your Xeno-Canto Recordings". Enter your Recordist Name and API key, then click "Fetch Recordings" to pull your entire library into an interactive grid.
Q: What happens when I click on the XC Number link in the grid?
A: Clicking the XC number is a smart shortcut. If the recording already has annotations on Xeno-Canto, they will be automatically downloaded. If there are no annotations yet, the audio will load directly into the spectrogram so you can immediately begin creating new annotations!
Q: How can I adjust the recordings grid view?
A: The grid is highly customizable and automatically saves your preferred layout across sessions:
• Customize Columns: Click the "Customize Columns" button above the grid to toggle visibility of over 30 different metadata fields.
• Adjust Widths: Hover over the borders between column headers and drag to manually resize them to your liking.
• Filtering & Sorting: Use the text inputs or dropdowns directly beneath each column header to filter your recordings. Click the header title itself to sort the rows ascending or descending.
• Details View: For metadata fields you choose to keep hidden, simply click the blue "Info" (i) icon on the far left side of any row to view all remaining properties in a popup.
Exporting Data & Media
Q: How to export the currently loaded audio as a WAV file?
A: Open the left hamburger menu and click "Export Sound File". This will download a new `.wav` file of your current audio, which includes any destructive edits (cuts, silences, filters) you applied during the session.
Q: How to generate and save individual WAV audio clips for every annotation box?
A: Open the left hamburger menu and click "Generate Audio Clips". Spectrolipi will slice the audio track based on the start and end times of your annotations and download them as a batch of individual files directly to your computer.
Q: How to export a scrolling video of the spectrogram?
A: Open the left hamburger menu and click "Export Video". This will capture a synchronized, scrolling video of the visual spectrogram canvas matched with the audio playback, perfect for sharing visual examples.