MetaMuLate v9.95! User Guide
Welcome to MetaMuLate, the advanced metadata reconciliation tool. This system allows you to aggregate, verify, and consolidate music metadata from multiple authoritative sources, now including Snowflake.
🚀 Quick Start with Local CORS Proxy
Recommended: Use the included Go binary CORS proxy for maximum reliability and security.
- Windows: Double-click
start-windows.bat
- macOS: Double-click
start-mac.sh (or run chmod +x start-mac.sh && ./start-mac.sh in Terminal)
The proxy will start on http://localhost:8080 and the app will auto-detect it. Keep the terminal window open while using MetaMuLate.
🔧 Self-Hosted CORS Proxy Deployment
For shared team use or permanent deployment, host your own CORS proxy:
Option 1: Deploy to Heroku (Free Tier)
git clone https://github.com/Rob--W/cors-anywhere.git
cd cors-anywhere
heroku create my-cors-proxy
git push heroku master
Your proxy will be at: https://my-cors-proxy.herokuapp.com/
Option 2: Deploy to Railway.app
1. Fork cors-anywhere on GitHub
2. Connect to Railway.app
3. Deploy from your forked repo
4. Add environment variable: PORT=8080
Option 3: Use Included Go Binary (Localhost)
// Build from source (requires Go installed):
go build -o cors-proxy cors-proxy.go
// Or use pre-compiled binaries:
// Windows: cors-proxy.exe
// macOS Intel: cors-proxy-mac-intel
// macOS ARM: cors-proxy-mac-arm
// Run:
./cors-proxy
// Proxy runs on http://localhost:8080
Configure Custom Proxy
In the Connections modal, update the "CORS Proxy URL" field to your deployed proxy URL.
1. Setup & Connections
Before beginning, click the Connections button. While some sources (iTunes Public, Lyrics.ovh) work out of the box, others require API keys:
- Apple Music: Requires a Developer Token. If not provided, the system falls back to the iTunes Search API (limited fields).
- Discogs: Requires a Personal Access Token (search endpoint requires auth). Free to generate in your Discogs Developer settings.
- Genius: Requires a Client Access Token.
- Snowflake: Multiple connection methods available (see below).
🔌 Snowflake Connection Methods
MetaMuLate v9.95! supports secure methods to connect to Snowflake:
1. Local Proxy with SSO (Recommended)
Run the included metamulate-proxy binary. Supports SSO/External Browser authentication - credentials are managed securely on your machine, never stored in the browser.
./start.sh # macOS/Linux
start.bat # Windows
SSO authentication: Browser opens for corporate login, tokens managed by proxy.
2. Direct SQL API (Hosted Environments Only)
When MetaMuLate is served from a web server (https://), it can connect directly to Snowflake's SQL API. This method is NOT available when running as a local file (file://).
Note: Credentials are stored in browser localStorage and visible in DevTools.
3. Auto-Detect (Default)
Let MetaMuLate automatically choose the best method based on your environment:
- Local proxy running → Uses Local Proxy with SSO (most secure)
- Hosted environment (https) → Uses Direct SQL API
- File:// protocol without proxy → Connection blocked - requires Local Proxy
⚠️ Snowflake Security
Important: For production and enterprise use, always use the Local Proxy method with SSO authentication. Direct connections store credentials in the browser which is not suitable for sensitive environments.
Security Note: Third-party CORS proxies are NOT supported for Snowflake connections as they could expose your credentials to untrusted services.
2. Discovery & Scraping
Enter an Artist name in the top left search bar. The system uses the Apple Music/iTunes catalog as the "anchor" source to find tracks. Results are automatically sorted by Authority Score - a composite ranking that prioritizes:
⭐ Authority Score Calculation
The Authority Score is a weighted metric that ranks metadata quality and authenticity (0-200+ scale):
- ISRC Presence (+50 points) - Official recording identifier indicates authoritative metadata
- Metadata Completeness (+2 per field) - Evaluates 10 core fields: track name, artist, album, ISRC, P-Line, year, genre, duration, composer, and label
- Original Release Bonus - Pre-2000 releases (+30 pts), 2000-2009 (+15 pts) - Prioritizes original recordings over reissues
- P-Line/Legal Metadata (+10 points) - Presence of copyright information
- Label Information (+10 points) - Presence of record label indicates commercial release
- Composer Credits (+5 points) - Deep metadata showing detailed rights information
- MusicBrainz Relevance Score (0-100 variable) - Native relevance scoring from MusicBrainz API
Example: A track with ISRC (50), all 10 fields filled (20), released in 1997 (30), P-Line (10), Label (10), and Composer (5) would score 125 before MusicBrainz bonus.
Each result displays: ISRC badge, ⭐ Authority Score, Completeness %, and Release Year.
3. The Matrix & Provenance
The central grid displays data from all connected sources side-by-side.
Important: Every data point has an icon. Clicking this opens the source verification page. We do not generate mock data. if a field says "N/A", the source did not provide it.
4. Correlation & Logic
The system employs a "Gold Standard" matching algorithm. When reconciling, it prioritizes sources that provide strict ISRC matches, UPCs, and high text-similarity scores. Exact matches > Fuzzy matches.
5. Golden Record & Export
Click any cell in the matrix to promote that value to the "Golden Record" on the right. Once satisfied, click Export to download an Excel file of your consolidated metadata.
6. Data Management & Export/Import
The Data & Config menu provides three distinct export/import categories:
📦 Session Data (Scraped Metadata)
- Export JSON: Save all tracks, golden records, and scraped data. Use this to pause work and resume later by re-importing.
- Export Excel: Create a multi-sheet XLSX file with Golden Records, All Tracks, and per-source data sheets (MusicBrainz, Discogs, etc.). Ideal for analysis or sharing.
- Import JSON: Restore a previously exported session to continue work.
⚙️ Configuration (No Keys)
- Export: Save your matrix column settings, timeout values, custom fields, and preferences. Does NOT include API keys.
- Import: Restore configuration settings on a new device or after a reset.
🔑 API Keys (Sensitive)
- Export: Save only your API keys and credentials. ⚠️ Contains sensitive data in plain text - keep secure!
- Import: Restore API keys separately from other configuration.
Tip: The green Export button in the header is a quick shortcut to export just the Golden Records as an Excel file.
🐛 Debug Mode
Enable Debug Mode in the console panel to see complete request/response payloads for all API calls, including verification attempts. Useful for troubleshooting connection issues.