From 49fc3a273f2867c1cdd00d62b9fb99f22b4f4630 Mon Sep 17 00:00:00 2001 From: Broque Thomas <26755000+Nezreka@users.noreply.github.com> Date: Sun, 1 Mar 2026 16:53:40 -0800 Subject: [PATCH] Create IMPORT-STAGING-GUIDE.md --- Support/IMPORT-STAGING-GUIDE.md | 190 ++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 Support/IMPORT-STAGING-GUIDE.md diff --git a/Support/IMPORT-STAGING-GUIDE.md b/Support/IMPORT-STAGING-GUIDE.md new file mode 100644 index 00000000..3024c812 --- /dev/null +++ b/Support/IMPORT-STAGING-GUIDE.md @@ -0,0 +1,190 @@ +# Import & Staging Folder Guide + +## Overview + +Got a mess of audio files — ripped CDs, old downloads, files from other apps — that you want in your library with proper metadata? That's what Import is for. + +Drop your unorganized files into the staging folder, open the Import page, and match them to albums or tracks. SoulSync takes care of the rest: full metadata tagging (artist, album, track number, genres), album art embedding, lyrics fetching, renaming to your path template, and moving everything into your organized library. Files go from a chaotic pile to properly tagged, organized tracks in your transfer folder. + +--- + +## Setup + +### 1. Configure the Staging Path + +In **Settings**, find the **"Import Staging Dir"** field. The default is `./Staging`. + +For Docker, map a host folder to the container: + +```yaml +volumes: + - /path/to/your/staging:/app/Staging +``` + +Then set the staging path in SoulSync settings to `/app/Staging`. + +### 2. Add Files to the Staging Folder + +Drop audio files into your staging folder. Supported formats: + +| Format | Extension | +|--------|-----------| +| FLAC | `.flac` | +| MP3 | `.mp3` | +| AAC | `.aac`, `.m4a` | +| OGG Vorbis | `.ogg` | +| Opus | `.opus` | +| WAV | `.wav` | +| WMA | `.wma` | +| AIFF | `.aiff`, `.aif` | +| Monkey's Audio | `.ape` | + +You can organize files in subfolders — SoulSync reads folder names as hints for album suggestions (e.g., a folder named `Artist - Album` improves matching). + +--- + +## Using the Import Page + +Click **Import** in the sidebar to open the Import page. The top bar shows your staging folder path, file count, and total size. Click **Refresh** to re-scan if you've added new files. + +There are two modes: **Albums** and **Singles**. + +--- + +### Album Mode + +Use this when your staging files belong to a complete album (or part of one). + +#### Step 1: Find the Album + +SoulSync automatically suggests albums based on your files' metadata tags and folder structure. These appear as album cards with cover art. + +If the right album isn't suggested, use the **search bar** to find it by name. + +#### Step 2: Select an Album + +Click an album card to select it. You'll see: +- Album cover art, title, artist, track count, and release year +- The full tracklist with track numbers and names +- Automatic file-to-track matching with confidence percentages + +#### Step 3: Review Matches + +SoulSync matches your staging files to album tracks using title similarity and track numbering. Each match shows a confidence percentage: + +- **70%+** — High confidence, likely correct +- **Below 70%** — Worth double-checking +- **100%** — You assigned it manually + +Unmatched files appear in an **"Unmatched Files"** pool at the bottom. + +#### Step 4: Fix Mismatches (Drag-and-Drop) + +If a file was matched to the wrong track: + +1. **Drag** a file from the unmatched pool +2. **Drop** it onto the correct track row +3. The previous match (if any) returns to the unmatched pool + +To remove a match, click the **X** button next to the matched file. + +You can also click **"Re-match Automatically"** to reset all manual overrides and let SoulSync re-run its matching. + +**On mobile:** Tap a file chip to select it, then tap the track row to assign it. + +#### Step 5: Process + +The bottom of the page shows how many tracks are matched (e.g., "8 of 12 tracks matched"). Click **"Process X Tracks"** to start importing. + +--- + +### Singles Mode + +Use this for individual tracks that aren't part of an album. + +#### Step 1: Browse Files + +All staging files appear as a list showing filename and any metadata tags found. + +#### Step 2: Identify Tracks + +Click **"Identify"** next to a file to search for the matching Spotify track. Select the correct result. + +#### Step 3: Select and Process + +Check the boxes next to files you want to import. Use **"Select All"** to toggle everything. Click **"Process Selected (N)"** to queue them. + +--- + +## Processing Queue + +When you start an import, a processing queue appears showing real-time progress: + +- **Progress bar** fills as tracks complete +- **Status** shows counts like "3/10" (processed/total) +- **Errors** are shown inline (e.g., "8/10 (2 err)") +- **"Clear finished"** button removes completed/errored jobs + +Processing continues in the background even if you navigate away from the Import page. After all jobs finish, the staging folder is automatically re-scanned and suggestions refresh. + +### What Processing Does + +For each matched track, SoulSync: +1. Enriches the file with full Spotify metadata (artist, album, track number, disc number, genres) +2. Embeds album artwork +3. Fetches synchronized lyrics (LRC) when available +4. Renames and moves the file to your transfer folder using your configured path template +5. Triggers a media server library scan (if connected) + +--- + +## Tips + +- **Organize by album** — Putting files in an `Artist - Album` subfolder significantly improves automatic suggestions and matching +- **Tag your files first** — Files with proper ID3/metadata tags get better automatic matches +- **Start with Album mode** — It's faster for grouped files since you match a whole album at once +- **Use Singles mode for loose tracks** — Mixtapes, random downloads, one-offs +- **Check confidence scores** — Low percentages mean the match might be wrong +- **Drag-and-drop is your friend** — Faster than re-searching when a match is close but wrong + +--- + +## Troubleshooting + +| Problem | Solution | +|---------|----------| +| No files showing up | Check that your staging path is correct in Settings and the folder isn't empty. Click Refresh. | +| No album suggestions | Files may lack metadata tags. Try searching manually by album name. | +| Wrong track matched | Drag the correct file from the unmatched pool onto the track, or click X to unmatch and try again. | +| Processing fails | Check that your transfer path is writable. Enable DEBUG logging in Settings and check `logs/app.log`. | +| Files not disappearing after import | Successfully processed files are moved to your transfer folder. Check there. Failed files remain in staging. | +| Docker: staging folder empty | Verify your volume mapping points to the right host folder and the container path matches your Settings value. | + +--- + +## Docker Example + +```yaml +volumes: + # Your staging folder for imports + - /mnt/user/Music/Staging:/app/Staging + + # Where processed files end up + - /mnt/user/Music/Library:/app/Transfer:rw +``` + +**SoulSync Settings:** +- Import Staging Dir: `/app/Staging` +- Transfer Path: `/app/Transfer` + +**Workflow:** +``` +1. You drop files into /mnt/user/Music/Staging (host) + → /app/Staging (container) + +2. Open Import page → Match to albums/tracks + +3. Process → Files move to /app/Transfer (container) + → /mnt/user/Music/Library (host) + → Media server picks them up +```