Shanty/Main
1
0
Fork 0
Code Issues 18 Pull Requests Actions Packages Projects Releases Wiki Activity

Implement music file organization in shanty-org #5

New Issue
Closed
opened 2026-03-17 14:25:21 -04:00 by connor · 0 comments
connor commented 2026-03-17 14:25:21 -04:00
Owner
Copy Link

The shanty-org crate is responsible for organizing music files into a clean directory structure and renaming them according to a configurable format. Many music libraries are a mess of random filenames and flat folders — this crate fixes that.

This issue covers:

  1. Directory structure generation — given a target root directory and a format template, move/copy music files into the correct structure. The default structure should be:

    {root}/{artist}/{album}/{track_number} - {title}.{ext}

    For example: Music/Pink Floyd/The Dark Side of the Moon/03 - Time.flac

  2. Format templates — support a simple template syntax for both directory structure and filename. Available variables should include at minimum:

    • {artist} — track or album artist
    • {album_artist} — album artist (falls back to artist)
    • {album} — album name
    • {title} — track title
    • {track_number} — zero-padded track number (e.g., "03")
    • {disc_number} — disc number
    • {year} — release year
    • {genre} — genre
    • {ext} — file extension

  3. Safe file operations — this crate moves actual files, so it must be very careful:

    • Sanitize filenames (remove/replace characters invalid on the target filesystem)
    • Handle conflicts (what if two files resolve to the same target path?)
    • Support dry-run mode to preview changes before executing
    • Log all file moves so the operation could theoretically be reversed
    • Update the file path in the shanty-db database after moving

  4. CLI interface — the shanty-org binary should accept:

    • --source <dir> — source directory (or use DB paths)
    • --target <dir> — target root directory
    • --format <template> — format template (with a sensible default)
    • --dry-run — preview changes without moving files
    • --copy vs --move — whether to copy or move files (default: move)
    • --from-db — organize all tracks known to the database

Design Considerations

  • This crate can operate independently of the database — if someone just has a directory of music files with embedded tags, it should be able to read those tags and organize the files. But when used with the database, it should read metadata from there (faster than re-reading tags) and update paths afterward.
  • Handle the case where metadata is incomplete — if there's no album, put the file in an "Unknown Album" folder; if no artist, use "Unknown Artist"; etc.
  • Empty directories left behind after moving files should be cleaned up.
  • On failure mid-operation, the state should be recoverable (already-moved files should still be tracked).

Acceptance Criteria

  • Files are moved/copied into the correct directory structure based on metadata
  • Format templates work with all specified variables
  • --dry-run shows planned moves without executing them
  • Filenames are sanitized for filesystem safety
  • Conflicts are detected and handled (e.g., appending a number)
  • Database file paths are updated after moving (when using --from-db)
  • Works standalone (reading embedded tags) without requiring the database
  • Empty source directories are cleaned up after moves
  • CLI interface works as specified
  • Integration test: create temp files with metadata, organize them, verify the resulting directory structure

Dependencies

  • Issue #1 (workspace scaffolding)
  • Issue #2 (shared database schema)
  • Issue #3 (music indexing — beneficial but not strictly required)
The `shanty-org` crate is responsible for organizing music files into a clean directory structure and renaming them according to a configurable format. Many music libraries are a mess of random filenames and flat folders — this crate fixes that. This issue covers: 1. **Directory structure generation** — given a target root directory and a format template, move/copy music files into the correct structure. The default structure should be: ``` {root}/{artist}/{album}/{track_number} - {title}.{ext} ``` For example: `Music/Pink Floyd/The Dark Side of the Moon/03 - Time.flac` 2. **Format templates** — support a simple template syntax for both directory structure and filename. Available variables should include at minimum: - `{artist}` — track or album artist - `{album_artist}` — album artist (falls back to artist) - `{album}` — album name - `{title}` — track title - `{track_number}` — zero-padded track number (e.g., "03") - `{disc_number}` — disc number - `{year}` — release year - `{genre}` — genre - `{ext}` — file extension 3. **Safe file operations** — this crate moves actual files, so it must be very careful: - Sanitize filenames (remove/replace characters invalid on the target filesystem) - Handle conflicts (what if two files resolve to the same target path?) - Support dry-run mode to preview changes before executing - Log all file moves so the operation could theoretically be reversed - Update the file path in the `shanty-db` database after moving 4. **CLI interface** — the `shanty-org` binary should accept: - `--source <dir>` — source directory (or use DB paths) - `--target <dir>` — target root directory - `--format <template>` — format template (with a sensible default) - `--dry-run` — preview changes without moving files - `--copy` vs `--move` — whether to copy or move files (default: move) - `--from-db` — organize all tracks known to the database ### Design Considerations - This crate can operate independently of the database — if someone just has a directory of music files with embedded tags, it should be able to read those tags and organize the files. But when used with the database, it should read metadata from there (faster than re-reading tags) and update paths afterward. - Handle the case where metadata is incomplete — if there's no album, put the file in an "Unknown Album" folder; if no artist, use "Unknown Artist"; etc. - Empty directories left behind after moving files should be cleaned up. - On failure mid-operation, the state should be recoverable (already-moved files should still be tracked). ### Acceptance Criteria - [ ] Files are moved/copied into the correct directory structure based on metadata - [ ] Format templates work with all specified variables - [ ] `--dry-run` shows planned moves without executing them - [ ] Filenames are sanitized for filesystem safety - [ ] Conflicts are detected and handled (e.g., appending a number) - [ ] Database file paths are updated after moving (when using `--from-db`) - [ ] Works standalone (reading embedded tags) without requiring the database - [ ] Empty source directories are cleaned up after moves - [ ] CLI interface works as specified - [ ] Integration test: create temp files with metadata, organize them, verify the resulting directory structure ### Dependencies - Issue #1 (workspace scaffolding) - Issue #2 (shared database schema) - Issue #3 (music indexing — beneficial but not strictly required)
connor added the HighPriorityMVP labels 2026-03-17 14:27:09 -04:00
connor started working 2026-03-17 18:15:35 -04:00
connor worked for 10 minutes 2026-03-17 18:26:24 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
LowPriority
MediumPriority
HighPriority
MVP
No Label HighPriority MVP
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
connor
No Assignees
1 Participants
Notifications
Total Time Spent: 10 minutes
connor
10 minutes
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Shanty/Main#5
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?