audiofiles/ testing

Alpha testing guide — features, workflows, and edge cases.

Version 0.3.0. Standalone desktop app. 560 automated tests. This document covers the human side.

This guide covers every user-facing feature in audiofiles, organized into testable workflows. Each section has a checklist of things to verify. The goal of alpha testing is to find bugs, rough edges, and missing affordances before the app reaches real users. Test on macOS first (primary platform), then Linux where possible.

How to use this document. Work through each section in order. Check off items as you go. The first three sections (First Launch, Import, Analysis) form the critical path — every user will hit these. Later sections cover power-user features. Report bugs with steps to reproduce, the theme you were using, and the exact error message if one appeared.

Feature Map

Storage & Import

Content-addressed store (SHA-256). Import WAV, FLAC, MP3, OGG, AIFF. Three strategies: new VFS, merge, flat. Drag-and-drop or CLI. Folder tagging on import.

Virtual File System

Multiple independent VFS roots. Directories, sample links, breadcrumb nav. Rename, move, delete with cascade. Same sample in unlimited hierarchies.

Analysis Pipeline

Loudness (peak/RMS/LUFS), BPM, key, spectral, loop detection, classification (12 categories), waveform, fingerprint. Each stage individually toggleable.

Search & Filter

Text search, BPM range, duration range, key (exact + compatible), classification multi-select, tag prefix. Smart folders save filter presets.

Tags & Suggestions

Hierarchical dot-notation. Auto-suggestions from analysis. Accept/reject per suggestion. Bulk add/remove. Tag on import by folder name.

Export & Devices

14 hardware sampler profiles. Sample rate conversion, bit depth dithering, filename sanitization. Rhai-scripted profiles. Background worker.

Preview & Instrument

Inline audio preview with waveform. Streaming decode for long files. Chromatic + multi-sample MIDI instrument. 8-voice polyphony, ADSR envelopes.

Sync & Themes

Cloud sync via SyncKit (E2E encrypted). 17 bundled themes. Native drag-out to Finder/DAWs. Collections. Similarity + duplicate search.

Keyboard Reference

j / ↓ Move down

k / ↑ Move up

Enter Open / play

Backspace Go up

Space Play / pause

Delete Delete selected

/ Focus search

Cmd+A Select all

Cmd+Z Undo

Cmd+T Bulk tag

F2 Bulk rename

F1 Help overlay

I Instrument panel

S Toggle sidebar

D Toggle detail

Esc Dismiss / clear

Shift+Click Range select

Cmd+Click Toggle select

1. First Launch

Critical App opens without errors. Window appears, default "Library" VFS is created.
Critical Empty state is clear: no samples, no errors, status bar is empty.
Sidebar shows "Library" VFS. Detail panel and sidebar are both visible by default.
Theme is "audiofiles" (default). All UI elements are legible and properly colored.
F1 opens the help overlay with keyboard shortcuts. F1 again or Escape closes it.
Window is resizable. Detail panel auto-hides below 700px width.
Toggle sidebar (S key), detail panel (D key). Both remember state across navigation.

2. Import Workflow

Test with varied content. Use a folder containing WAV, FLAC, MP3, OGG, and AIFF files. Include subfolders, files with spaces and special characters in names, at least one corrupt or empty file, and at least one very large file (>100MB). The more diverse the test material, the better.

Import Configuration

Critical Drop a folder onto the app window. Configure Import screen appears.
Three import strategies available: New VFS (default), Merge Into, Flat.
New VFS name defaults to the folder name. Editable.
Merge Into shows a dropdown of existing VFS roots.
Cancel returns to normal browsing without changes.

Import Progress

Critical Progress bar advances. "Scanning for audio files..." spinner during walk phase.
Current filename updates as files are processed.
Error count appears in red if files fail (click to expand details).
Cancel stops import mid-way. Partially imported files remain valid.
Retry button re-opens configure screen with previous source path.

Folder Tagging

After import, Tag Folders screen shows top-level subfolders.
Each folder has an editable tag input. Comma-separated tags work.
"Apply Tags" adds tags to all samples in that folder, then proceeds to analysis.
"Skip" proceeds to analysis without tagging.

Post-Import Error Summary

Important If any files failed import or analysis, the Review Errors screen appears.
Analysis errors show sample name, error message, and per-row "Remove" button.
Import errors show file path and error message (informational, no actions).
"Keep All" dismisses errors and returns to browsing.
"Remove All Failed" deletes failed samples from the store and returns to browsing.
Individual "Remove" buttons delete one failed sample at a time.

Edge Cases

Import the same folder twice: duplicates are skipped, count shown in status.
Import an empty folder: no samples imported, status reflects this.
Import a single file via drag-and-drop: immediate import + analysis, no configure screen.
CLI import: audiofiles-app /path/to/folder opens app and starts import.
Files with no extension or wrong extension: handled gracefully (error or skip).

3. Analysis

Configuration

Analysis config screen shows toggle checkboxes for each stage.
All stages enabled by default. Each can be individually disabled.
"Analyze" starts the background worker. "Cancel" returns to browsing.

Progress & Results

Critical Progress bar advances. Current sample name shown.
Errors accumulated during analysis show in expandable error list.
Cancel stops analysis. Already-analyzed samples keep their results.
After analysis, Review Suggestions screen shows auto-generated tags.

Tag Suggestions

Important Each sample shows proposed tags (BPM, key, classification).
Tags are pre-accepted. Click to reject individual suggestions.
"Apply" commits accepted tags. "Skip" discards all suggestions.
Navigate between samples using the review UI.

Detail Panel After Analysis

Select an analyzed sample. Detail panel shows: duration, BPM, key, classification badge.
Waveform renders correctly (stereo peaks, theme-colored).
Sample rate, channels, peak dB, RMS dB, LUFS all populated.
Loop detection shows Yes/No.

4. File List & Navigation

Critical Directories sort before samples. Names sort case-insensitively.
Click column headers to sort by Name, BPM, Key, Duration, Classification.
Click same header again to reverse direction. Third click resets to Name ascending.
Enter a directory (Enter or double-click). Breadcrumb updates. ".." entry at top.
Go up via Backspace, Left arrow, or clicking ".." entry.
Breadcrumb segments are clickable to jump to ancestors.
Shift+Click range select. Cmd+Click toggle select. Cmd+A select all.
Selection persists across sort changes. Clears on navigation.

5. Search & Filtering

Text Search

Type in search bar or press "/" to focus it. Results update as you type.
Escape clears search and restores full listing.
Search scope: current folder (default) or global.
Search with special characters: quotes, ampersands, Unicode.

Filter Panel

Open filter panel (toolbar button). Shows BPM, duration, key, classification, tag filters.
BPM range slider: drag min/max. Only samples in range appear.
Key filter: select keys, major/minor/both, exact vs compatible mode.
Compatible mode includes relative + circle-of-fifths neighbors.
Classification checkboxes filter to selected categories.
Tag prefix filter: type partial tag, matching samples shown.
Multiple filters combine with AND logic.

Smart Folders

With a filter active, save as smart folder. Appears in sidebar.
Click smart folder to re-activate its filter.
Delete smart folder via context menu.
Smart folders are per-VFS and persist across sessions.

Similarity Search

Right-click sample → "Find Similar": shows top 50 matches by spectral features.
Right-click → "Find Near-Duplicates": shows matches by peak envelope fingerprint.
Status bar shows match count. Clear with toolbar button.

6. Bulk Operations

Bulk Tag (Cmd+T)

Select 2+ samples. Cmd+T opens tag modal. Add or Remove mode toggle.
Enter a tag (dot-notation). "Apply" adds/removes to all selected.
Cmd+Z undoes the operation.
Empty tag input is a no-op (no crash, no undo entry).

Bulk Rename (F2)

Select 2+ samples. F2 opens rename modal. Pattern input with tokens.
Tokens: {name}, {bpm}, {key}, {class}, {duration}, {n}/{nn}/{nnn}.
Live preview shows old → new names. Validation errors appear inline.
Duplicate names auto-deduplicated with "(2)" suffix.
Invalid pattern (unknown token) shows error, prevents apply.
Cmd+Z undoes the rename.

Bulk Move & Delete

Select items, open move modal. Choose target directory from dropdown.
Execute move. Items disappear from current view. Cmd+Z undoes.
Delete key on selection shows confirmation dialog. "Delete" executes, Cmd+Z undoes.
Multi-select delete: all selected items removed. Tags preserved in undo.
Undo stack maxes at 50 operations.

7. VFS Management

Create new VFS via sidebar. Name input modal. Appears in sidebar list.
Switch VFS by clicking its name. Navigation resets to root.
Rename VFS via context menu. Name updates in sidebar.
Delete VFS via context menu (only if >1 exists). Confirmation dialog.
Create directory via toolbar button. Rename via context menu.
Delete directory cascades all children (confirmation required).

8. Audio Preview

Critical Select sample and press Enter or Space. Audio plays through system output.
Waveform cursor tracks playback position in detail panel.
Click waveform to seek to position.
Space pauses and resumes. Selecting another sample switches preview.
Long files (>30s) use streaming decode: playback starts within ~0.5s.
Short files decode fully before playback (instant start).
All five formats play correctly: WAV, FLAC, MP3, OGG, AIFF.
Mono files play as centered stereo. Multi-channel downmixes to stereo.
Status bar shows "Playing: filename" during playback.

9. MIDI Instrument Mode

Chromatic Mode

Right-click sample → "Load to Instrument". Instrument panel opens at bottom.
Press I to toggle panel visibility.
Play notes via on-screen piano or MIDI keyboard.
Root note auto-detected from key analysis (defaults to C3 if unknown).
Pitch shifts correctly across the keyboard range.
8-voice polyphony: play more than 8 notes, oldest stolen.

Multi-Sample Mode

Add multiple zones with different key ranges.
Zone bars visible on the piano keyboard display.
Remove zone button removes the zone and kills its active voices.
ADSR envelope: audible attack, decay, sustain, release on each voice.

10. Export

Configuration

Critical Start export flow. Config screen shows item count, format options, destination.
Device profile picker: 14 profiles available. Selecting one adjusts format/rate/depth.
Manual mode: choose format (WAV/AIFF/Original), sample rate, bit depth, channels.
Flatten toggle: export without directory structure.
Metadata sidecar toggle: writes .audiofiles.json per sample.
Destination picker: defaults to ~/Downloads/audiofiles Export.

Export Progress & Completion

Progress bar advances. Current filename shown. Cancel stops mid-export.
Completion screen shows total exported and any errors.
Exported files are at the correct sample rate, bit depth, and format.
Filenames sanitized per device profile rules (length, case, separators).
Export to read-only destination: error shown, not a crash.

Device Profile Spot Checks

SP-404 MKII: WAV, 48kHz, 16-bit, stereo
Digitakt: WAV, 48kHz, 16-bit, mono
MPC: WAV, 44.1kHz, 16-bit, stereo
OP-1: AIFF, 44.1kHz, 16-bit, stereo
M8: WAV, 44.1kHz, 16-bit, mono
Deluge: WAV, 44.1kHz, 16/24-bit, stereo

11. Themes

Theme picker in toolbar. All 17 themes selectable.
Switching theme updates all colors immediately. No leftover artifacts.
Theme preference persists across app restarts.
Waveform colors follow theme. Classification badges follow theme.
Progress bars, buttons, modals all correctly themed.
Light themes (ayu-light, flatwhite, gruvbox-light, rosepine-dawn, catppuccin-latte) have readable text.
High-contrast theme meets accessibility requirements.

12. Collections

Create collection via sidebar. Name input. Appears in sidebar with (0) count.
Right-click sample → "Add to Collection". Count updates.
Click collection name to view members. File list shows only those samples.
Remove sample from collection. Deactivate collection view to return to normal.
Rename and delete collections via context menu.
A sample can belong to multiple collections simultaneously.

13. Drag-Out (macOS)

Critical Drag a sample from the file list to the Desktop. File appears with correct name.
Drag to a DAW (REAPER, Ableton, Logic). Sample loads in the DAW.
Multi-file drag: select multiple, drag. All files transferred.
Drag-out cooldown: rapid successive drags do not cause duplicate transfers.
Drag a file that has been deleted from the store: handled gracefully.

14. Cloud Sync

Open sync panel (toolbar icon). Shows "Disconnected" state.
Auth flow: enter code, opens browser for Makenot.work login.
After auth, encryption setup: enter passphrase. Keys derived and stored.
Sync Now: pushes metadata. Status updates to "Last synced: ..."
Auto-sync toggle with interval picker (5m, 15m, 30m, 1h).
Disconnect: clears credentials. Returns to Disconnected state.
Per-VFS sync toggle: metadata always syncs, audio blobs opt-in.
Wrong passphrase: clear error message, not a crash.

15. Edge Cases & Stress

Data Integrity

Critical Close and reopen the app. All data persists: VFS, tags, analysis, collections.
Import the same folder twice. No duplicate samples created in the store.
Delete a VFS. Samples remain in the store (still accessible from other VFS roots).
Delete the last reference to a sample. Store entry remains (content-addressed, never auto-deleted).

Error Handling

Import a folder with zero audio files: "No samples imported" message, no crash.
Import a corrupt WAV: import error captured, other files import normally.
Analyze a zero-length audio file: analysis error, sample still in store.
Analyze a file with unusual sample rate (8kHz, 192kHz): no crash.
Very short audio (<0.1s): analysis completes, BPM may be absent.
Very long audio (>10 min): streaming preview works, analysis completes.

Performance

Import a large library (1000+ files). Progress bar stays responsive.
Navigate a VFS with 500+ items in one directory. Scroll is smooth.
Run analysis on 100+ samples. Cancel mid-way. No orphaned workers.
Similarity search on a library of 500+ analyzed samples. Results appear in <2s.
Theme switch with many items visible: no frame drops.

Keyboard & Focus

All keyboard shortcuts work when file list has focus.
Shortcuts disabled when a text field has focus (except Escape).
Tab order through modals is logical.
Escape dismisses in priority: sync panel → bulk modal → confirm → help → search.

Multi-Select Interactions

Shift+Click from item 2 to item 8: items 2–8 selected.
Cmd+Click to deselect one item from a range: only that item deselected.
Shift+Down/Up extends selection one row at a time.
Select all (Cmd+A), then bulk tag, bulk rename, bulk move, bulk delete: all work.
Select ".." parent entry: excluded from bulk operations.

16. OTA Updates

On launch, update check runs in background (no UI freeze).
If update available: consent dialog with "Download" and "Not Now".
"Download" opens browser to download page.
"Not Now" dismisses. No repeated prompting in same session.
If no update available: no dialog, no indication. Silent.

When you find a bug. Note: (1) What you did. (2) What you expected. (3) What actually happened. (4) Which theme was active. (5) The exact error message or status text. (6) Whether the app crashed or recovered. File size and format of the involved sample if relevant.