Documentation & FAQ
Everything you need to know about Merge.
Guide
How to Create a Blend
Creating a blend takes less than a minute. Here are the steps:
1. Paste Playlist Links
Go to the Create Blend page. You and your friend each paste up to 5 YouTube Music playlist URLs. Merge extracts the tracks to understand your combined taste.
2. Upload Auth (Optional)
To include your Liked Songs or to export the final playlist to your YouTube Music library, upload your headers_auth.json file on the Auth Upload page. Skip this step if you only want to use public playlists and preview the result in the browser.
3. Generate & Export
Click Generate Blend. Merge analyzes your input, finds the overlap, scores compatibility, and builds a balanced playlist. Click Sync to YT Music to push it straight to your library.
Under the Hood
How the Algorithm Works
Merge builds a playlist in four sections:
- Shared Taste — tracks that appear in both libraries after normalization and fuzzy matching. These anchor the playlist.
- From User A / From User B — unique tracks from each listener, ranked by a scoring formula that weighs overlap ratio, artist similarity, and diversity. Tracks a user has across multiple playlists rank higher.
- New Discoveries — algorithmic radio picks seeded from your shared tracks, filtered to exclude anything either listener already knows.
Limits: 50 tracks total, 20 per section. Compatibility score uses the Dice coefficient: 2 × |shared| / (|A| + |B|) × 100.
Feedback
Improving Your Recommendations
Each track row shows 👍 👎 ⏭ controls on hover. Your feedback is stored and used to boost or penalize tracks in future blends — liked tracks score higher, skipped tracks score lower.
After viewing the playlist you can also rate the overall blend (1–5 stars) and leave a quick note ("Felt accurate" or "Missed the vibe"). This helps improve the algorithm over time.
All feedback is optional and dismissible — it never blocks your workflow.
Security
Privacy & Authentication
Why do you need my headers_auth.json?
YouTube Music does not have a public API for creating playlists or reading private Liked Songs. The only way to automate these features is by providing the session cookies your browser uses to prove you are logged in.
Is it safe?
Yes. The moment you upload your headers_auth.json, the backend encrypts it with AES-128-CBC (Fernet) before it ever touches the database. The raw file is never logged or stored in plaintext. It is used only for the duration of the fetch or export operation.
How do I get headers_auth.json?
- Open music.youtube.com and log in.
- Open DevTools (F12) → Network tab.
- Filter by
browseornextand click around the site to trigger a request. - Click the request → Request Headers → right-click → Copy object.
- Paste into a text file and save as
headers_auth.json.
FAQ
Frequently Asked Questions
Does this work with Spotify?
No. Merge is built specifically for YouTube Music. It uses ytmusicapi to fetch tracks and create playlists.
How many playlist links can I add?
Up to 5 per listener. Each link must be a valid YouTube Music playlist URL (music.youtube.com/playlist?list=...).
Is there a track limit?
Yes — 50 tracks total, 20 per section. This keeps the playlist focused and prevents YouTube Music rate-limiting.
My blend generation failed — what gives?
Make sure the playlists you provided are set to Public or Unlisted. Private playlists cannot be read by the server unless you have uploaded your auth file and the playlist belongs to you.
Is Merge free?
Yes. Merge is free, open-source, and community-driven. There are no subscriptions or lock-in. Check out the project on GitHub.