mirror of
https://gitea.baerentsen.space/FrederikBaerentsen/PicardScripts.git
synced 2026-03-31 15:07:49 +01:00
Added README and SCRIPT_GUIDE
This commit is contained in:
FrederikBaerentsen
@@ -0,0 +1,239 @@
|
||||
# MusicBrainz Picard File Naming Script v3.0
|
||||
|
||||
Automatically organize your music library with extensive customization options.
|
||||
|
||||
## What is This?
|
||||
|
||||
This is a powerful file naming script for [MusicBrainz Picard](https://picard.musicbrainz.org/) that automatically organizes your music collection into a clean, consistent directory structure. Instead of manually renaming files and creating folders, this script does it all for you based on metadata from MusicBrainz.
|
||||
|
||||
### File Organization
|
||||
|
||||
- **Picard_Rename_Script.txt** - The working script file (human-readable with full formatting)
|
||||
- **Picard_Rename_Script.ptsp** - Picard Script Package format for easy import into Picard
|
||||
- **README.md** - This beginner-friendly guide
|
||||
- **SCRIPT_GUIDE.md** - Complete technical reference and customization guide
|
||||
|
||||
### Key Features
|
||||
|
||||
- **Organized by artist** with alphabetical folders (A/, B/, C/, etc.)
|
||||
- **Separate albums, singles, EPs, and live recordings** into subfolders
|
||||
- **Multi-disc album support** with disc subfolders and subtitles
|
||||
- **Special handling** for Various Artists, Soundtracks, and Audiobooks
|
||||
- **Vinyl support** with MusicBrainz-style track numbering (A1, A2, B1, B2)
|
||||
- **Audio quality display** in filenames (bitrate, sample rate, CBR/VBR)
|
||||
- **Genre-based pre-sorting** for advanced organization
|
||||
- **Incomplete album handling** to keep partial albums separate
|
||||
- **Cross-platform** filename compatibility (Windows/Linux/macOS)
|
||||
|
||||
---
|
||||
|
||||
## Quick Example
|
||||
|
||||
**Before:** Messy files with inconsistent names
|
||||
```
|
||||
Various Artists - Now 80.mp3
|
||||
beatles-come together (1).mp3
|
||||
Pink Floyd - The Wall - CD1 - 01.flac
|
||||
```
|
||||
|
||||
**After:** Clean, organized structure
|
||||
```
|
||||
/B/Beatles, The/(1969) Abbey Road [CD - MP3]/01. Come Together [4m20s] [320 44100KHz CBR 2ch].mp3
|
||||
/P/Pink Floyd/(1979) The Wall [CD - FLAC]/Disc01/01. In the Flesh [3m19s] [96000KHz 24bit 6ch].flac
|
||||
/V/Various/(2011) Now That's What I Call Music! 80 [CD - MP3]/Disc01/01. Somebody That I Used to Know [4m04s].mp3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Required Software
|
||||
|
||||
1. **MusicBrainz Picard** (version 2.0 or later)
|
||||
- Download: [https://picard.musicbrainz.org/downloads/](https://picard.musicbrainz.org/downloads/)
|
||||
- Free and open-source music tagger
|
||||
|
||||
2. **Additional Artists Variables Plugin** (REQUIRED)
|
||||
- Author: Bob Swift [rdswift]
|
||||
- Source: [https://github.com/rdswift/picard-plugins/tree/2.0_RDS_Plugins](https://github.com/rdswift/picard-plugins/tree/2.0_RDS_Plugins)
|
||||
- License: GPL-2.0 or later
|
||||
- **Why needed:** This plugin provides enhanced artist variables that the script uses for proper artist sorting and featured artist detection
|
||||
|
||||
### Optional Plugins
|
||||
|
||||
3. **Last.fm.ng Plugin** (for genre-based category sorting)
|
||||
- Source: [https://github.com/fdemmer/Picard-Last.fm.ng-Plugin](https://github.com/fdemmer/Picard-Last.fm.ng-Plugin)
|
||||
- Only needed if you want to organize by genre/category at the root level
|
||||
|
||||
4. **Classical Extras Plugin** (for classical music workflow)
|
||||
- Only needed if you want special handling for classical music
|
||||
- Requires setting `$set(_isClassical,1)` in a separate script
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### Step 1: Install MusicBrainz Picard
|
||||
|
||||
1. Download Picard from [https://picard.musicbrainz.org/downloads/](https://picard.musicbrainz.org/downloads/)
|
||||
2. Install and launch the application
|
||||
|
||||
### Step 2: Install Required Plugin
|
||||
|
||||
1. In Picard, go to **Options -> Options -> Plugins**
|
||||
2. Click **Install plugin from URL**
|
||||
3. For the Additional Artists Variables plugin:
|
||||
- Download from [https://github.com/rdswift/picard-plugins/tree/2.0_RDS_Plugins](https://github.com/rdswift/picard-plugins/tree/2.0_RDS_Plugins)
|
||||
- Or search for "Additional Artists Variables" in the plugin list
|
||||
4. Enable the plugin and restart Picard
|
||||
|
||||
### Step 3: Install This Script
|
||||
|
||||
**Option A: Using the .ptsp package (recommended)**
|
||||
1. Download or use `Picard_Rename_Script.ptsp` from the repository
|
||||
2. In Picard, go to **Options -> Open file naming script editor -> File -> Import a script file**
|
||||
3. Click select the `Picard_Rename_Script.ptsp`
|
||||
4. Click **Open**
|
||||
|
||||
**Option B: Using the .txt file**
|
||||
1. Open the script file: `Picard_Rename_Script.txt`
|
||||
2. Copy the entire contents
|
||||
3. In Picard, go to **Options -> Open file naming script editor -> Script -> Add a new script -> Empty/blank script**
|
||||
4. Paste the script into the **Script** text box
|
||||
|
||||
### Step 4: Configure Destination Directory
|
||||
|
||||
1. In Picard, go to **Options -> Options -> File Naming**
|
||||
2. Check **Rename files when saving**
|
||||
3. Set **Destination directory** to your music library root
|
||||
- Example: `/Users/yourname/Music` or `D:\Music`
|
||||
4. Click **Make It So!**
|
||||
|
||||
### Step 5: Review Configuration (Optional)
|
||||
|
||||
The script uses sensible defaults, but you can customize it:
|
||||
|
||||
1. Open the script editor
|
||||
2. Find **SECTION 2: CONFIGURATION** (around line 115)
|
||||
3. Modify settings as needed (see Configuration Reference below)
|
||||
4. Copy and paste the updated script back into Picard
|
||||
|
||||
---
|
||||
|
||||
## How It Works: Default Configuration
|
||||
|
||||
The script uses sensible defaults that work great for most users. Here's what you get out of the box:
|
||||
|
||||
### Default Organization Structure
|
||||
|
||||
**Standard Album Example:**
|
||||
```
|
||||
/B/Beatles, The/(1969) Abbey Road [CD - MP3] [mbid] {catalog}/
|
||||
01. Come Together [4m20s] [320 44100KHz CBR 2ch].mp3
|
||||
02. Something [3m03s] [V0 44100KHz VBR 2ch].mp3
|
||||
03. Maxwell's Silver Hammer [3m27s] [96000KHz 16bit 2ch].flac
|
||||
...
|
||||
```
|
||||
|
||||
**Multi-Disc Album Example:**
|
||||
```
|
||||
/P/Pink Floyd/(1979) The Wall [CD - FLAC] [mbid] {catalog}/
|
||||
Disc01/
|
||||
01. In the Flesh [3m19s].flac
|
||||
02. The Thin Ice [2m29s].flac
|
||||
...
|
||||
Disc02/
|
||||
01. Hey You [4m42s].flac
|
||||
...
|
||||
```
|
||||
|
||||
**Various Artists Compilation Example:**
|
||||
```
|
||||
/Various/N/(2011) Now That's What I Call Music! 80 [CD - MP3] [mbid] {catalog}/
|
||||
Disc01/
|
||||
01. Somebody That I Used to Know [4m04s].mp3
|
||||
02. We Found Love [3m35s].mp3
|
||||
03. Rolling in the Deep [3m48s].mp3
|
||||
...
|
||||
```
|
||||
|
||||
**Albums, Singles, and EPs Separated Example:**
|
||||
```
|
||||
/M/Madonna/
|
||||
(1984) Like a Virgin [CD - MP3] [mbid] {catalog}/
|
||||
01. Material Girl [4m01s].mp3
|
||||
02. Like a Virgin [3m38s].mp3
|
||||
Singles/
|
||||
(1985) Into the Groove [CD - MP3] [mbid] {catalog}/
|
||||
01. Into the Groove [4m44s].mp3
|
||||
EP/
|
||||
(1989) Remixed Prayers [CD - MP3] [mbid] {catalog}/
|
||||
01. Like a Prayer (remix) [7m43s].mp3
|
||||
```
|
||||
|
||||
**Vinyl with MusicBrainz Track Numbers:**
|
||||
```
|
||||
/D/David Bowie/(1972) The Rise and Fall of Ziggy Stardust [Vinyl - MP3] [mbid] {catalog}/
|
||||
Side 1/
|
||||
A1. Five Years [4m43s].mp3
|
||||
A2. Soul Love [3m35s].mp3
|
||||
Side 2/
|
||||
B1. Lady Stardust [3m22s].mp3
|
||||
B2. Star [2m47s].mp3
|
||||
```
|
||||
|
||||
### Special Collections (Automatic)
|
||||
|
||||
The script automatically routes certain types of releases to dedicated directories:
|
||||
|
||||
- **Soundtracks** -> `/Soundtrack/G/Guardians of the Galaxy.../`
|
||||
- **Various Artists** -> `/Various/N/Now That's What I Call Music.../`
|
||||
- **Audiobooks** -> `/Audiobook/A/Audiobook Name.../`
|
||||
- **Podcasts** -> `/Podcast/P/Podcast Name.../`
|
||||
- **Incomplete Albums** -> `/- Partial/Artist/Album.../`
|
||||
|
||||
For detailed configuration options and advanced scenarios, see [SCRIPT_GUIDE.md](SCRIPT_GUIDE.md).
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
This script is licensed under **GPL-3.0** (GNU General Public License v3.0).
|
||||
|
||||
You are free to:
|
||||
- Use this script for any purpose
|
||||
- Modify it to suit your needs
|
||||
- Share it with others
|
||||
|
||||
Conditions:
|
||||
- If you distribute modified versions, you must also license them under GPL-3.0
|
||||
- Include a copy of the license and state changes made
|
||||
- Make source code available
|
||||
|
||||
---
|
||||
|
||||
## Credits
|
||||
|
||||
### Version History
|
||||
|
||||
**v1.0 - "MBP YA Magic-Script v2.7"**
|
||||
- Created by: amd/17500mph
|
||||
- Based on: "MBP Magic Script" by Ski-lleR
|
||||
- Character filter contributions: avibrazil
|
||||
- Source: [https://github.com/avibrazil/picard-scripting](https://github.com/avibrazil/picard-scripting)
|
||||
|
||||
**v2.0 - Custom Additions**
|
||||
- User modifications and enhancements
|
||||
|
||||
**v3.0 - Comprehensive Refactoring**
|
||||
- Complete reorganization and documentation
|
||||
- Inline examples and reference tables
|
||||
- Beginner-friendly documentation
|
||||
- Technical reference guide
|
||||
|
||||
### Plugin Credits
|
||||
|
||||
**Additional Artists Variables Plugin**
|
||||
- Author: Bob Swift [rdswift]
|
||||
- License: GPL-2.0 or later
|
||||
- Source: [https://github.com/rdswift/picard-plugins](https://github.com/rdswift/picard-plugins)
|
||||
Reference in New Issue
Block a user