From 0ffb5e50363813ec8f8d190b8e4daad07d0f78f6 Mon Sep 17 00:00:00 2001 From: Max Litruv Boonzaayer Date: Tue, 11 Nov 2025 11:20:26 +1100 Subject: [PATCH] Add comprehensive documentation for AudioSort including Home, Installation, FAQ, and Library Workflow --- FAQ.md | 31 +++++++++++++++++++++++++++++++ Home.md | 26 +++++++++++++++++++++++++- Installation.md | 39 +++++++++++++++++++++++++++++++++++++++ Library-Workflow.md | 37 +++++++++++++++++++++++++++++++++++++ 4 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 FAQ.md create mode 100644 Installation.md create mode 100644 Library-Workflow.md diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..9d81a4c --- /dev/null +++ b/FAQ.md @@ -0,0 +1,31 @@ +# FAQ + +## The app can’t find my library path + +Make sure the folder’s readable and you’ve got permission to create subfolders. +AudioSort stores its database under `%APPDATA%/AudioSort/` on Windows. + +## My waveform preview looks flat + +Waveform previews rebuild whenever files change. Try **Rescan Library** or tweak any bit of metadata to force a refresh. +If the file’s mostly silence, the flat preview might actually be accurate. + +## Duplicate groups look wrong + +Duplicate detection uses MD5 hashes of the raw audio data. +If two files sound the same but still don’t match, double-check their sample rate and bit depth — or normalise them externally before importing. + +## Organise File sent stuff to weird folders + +The organiser bases folders on the first UCS category in the file. +Check your category assignments and make sure the UCS catalog entry matches where you want it to go. + +## Can I use formats other than WAV? + +Nope. AudioSort’s pipeline is WAV-only so metadata stays consistent. +Convert other formats to WAV before adding them. + +## Where’s the UCS catalog stored? + +The app ships with `data/UCS.csv`. +On first run, it also copies that file into your user data directory for safe keeping. \ No newline at end of file diff --git a/Home.md b/Home.md index 7633e4a..1562f6e 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,25 @@ -Welcome to the AudioSort wiki! +# AudioSort Docs + +Welcome to the AudioSort wiki. This is where you’ll find setup info, workflow notes, and fixes for when things go sideways. It’s all built around the Electron app — your main tool for managing WAV libraries. + +## Highlights + +* **WAV-first setup** – automatically scans and detects duplicates using checksums +* **UCS tag categories** – full support with the built-in catalog +* **Waveform previews & splitting** – edit and trim sounds right in the app +* **Smart search** – fuzzy Fuse.js search with advanced metadata filters + +## Quick Start + +1. Download and install the desktop app ([Installation](Installation.md)) +2. Launch AudioSort and choose your library folder +3. Run **Rescan Library** from the menu to import your WAVs +4. Use tags, categories, and sorting tools to keep things neat + +## Navigation + +* [Installation](Installation.md) +* [Library Workflow](Library-Workflow.md) +* [FAQ](FAQ.md) + +Have an idea or found something that could be better? Open an issue or pull request in the main AudioSort repo. diff --git a/Installation.md b/Installation.md new file mode 100644 index 0000000..71ee643 --- /dev/null +++ b/Installation.md @@ -0,0 +1,39 @@ +# Installation + +AudioSort runs as a desktop app built with Electron. Follow the steps below to get it up and running on your machine. + +## System Requirements + +* Windows 10 or newer (64-bit) +* 4 GB of RAM or more +* Around 500 MB free for the app itself, plus space for your audio library +* WAV files (16/24-bit PCM recommended) + +## Windows Setup + +1. Download the latest `AudioSort Setup` installer from the releases page. +2. Run it and follow the prompts — you can pick a custom install location if you want. +3. Once it’s done, launch AudioSort from the Start Menu or the desktop shortcut. + +## Updating + +* You can install new versions right over the top of the old one — your settings and library data will stay safe. +* After updating, open the app and hit **Rescan Library** to keep everything in sync with your files. + +## Development Builds + +If you’re contributing or just want to run from source: + +```powershell +# clone the repo +git clone https://github.com/litruv/AudioSort.git +cd AudioSort + +# install dependencies +yarn install # or npm install + +# start the dev build +npm run dev +``` + +The dev script spins up Vite for the renderer, watches TypeScript, and runs Electron with live reload. diff --git a/Library-Workflow.md b/Library-Workflow.md new file mode 100644 index 0000000..6191049 --- /dev/null +++ b/Library-Workflow.md @@ -0,0 +1,37 @@ +# Library Workflow + +Here’s how the whole audio management loop works inside AudioSort — from scanning to tagging to cleaning things up. + +## Initial Scan + +1. Pick your library folder when you first launch the app (or later via **Settings → Library Path**). +2. Hit **Rescan Library** in the File menu — AudioSort will crawl all your `.wav` / `.wave` files, grabbing duration, bit depth, checksums, and waveform previews. +3. If you’ve deleted something from disk, it drops from the database automatically. Unchanged files keep their tags and metadata intact. + +## Tagging and Categories + +* AudioSort writes metadata straight into the WAV’s INFO chunk and keeps a copy in its SQLite database. +* UCS categories come from the built-in catalog. Tags are free-form — use whatever suits your workflow. +* The **File List** panel supports batch edits. Any updates stick even if you move or rename the files later. + +## Organising + +* **Organise File** moves a file based on its main category. Folder names are built from UCS codes plus your own custom label. +* **Rename** tweaks the file’s title and display name without changing its folder. +* The duplicate finder uses checksums to spot identical audio so you can merge or delete the extras fast. + +## Splitting Audio + +1. Open a file and drop in segments — set start/end times in ms, with optional names and tags. +2. Each split exports as a new WAV that inherits all metadata and links back to the parent via INFO data. +3. New segments get scanned automatically and show up right away for tagging. + +## Waveform Previews + +* Every file shows a mini waveform thumbnail after scanning. +* Previews rebuild themselves whenever you edit metadata or change the audio. + +## Search + +* The search bar does fuzzy matches on file names, tags, categories, and paths. +* You can also use filters like `author:` to dig into embedded metadata.