Skip to main content
BBPlayer supports importing playlists from popular Chinese music streaming services, automatically matching tracks to available content on Bilibili.

​
Supported Platforms

Import playlists from these external music services:
网易云音乐 (music.163.com)
  • Public playlists
  • Personal playlists (requires login)
  • Curated/editorial playlists
  • User-generated playlists
NetEase Cloud Music is one of China’s largest music streaming platforms with extensive metadata and high-quality playlists.

​
Import Methods

There are two ways to import external playlists into BBPlayer:

​
Method 1: URL Import

Quickly import by pasting a playlist URL.
1

Copy Playlist URL

From NetEase or QQ Music app/website:
  • Open the playlist you want to import
  • Tap the share button
  • Copy the playlist link
Supported URL formats:
NetEase: https://music.163.com/#/playlist?id=123456789
QQ Music: https://y.qq.com/n/ryqq/playlist/123456789
2

Open Import in BBPlayer

Navigate to Library > Playlists and tap the + button, then select “从外部导入” (Import from External).
3

Paste URL

Paste the playlist URL into the text field. BBPlayer will:
  • Parse the URL to extract playlist ID and source
  • Validate the playlist exists
  • Fetch playlist metadata
4

Start Matching

Tap “开始匹配” (Start Matching) to begin the import process.

​
Method 2: Direct Playlist Sync

For more advanced users, sync playlists programmatically: 
// Parse playlist URL (apps/mobile/src/lib/utils/playlistUrlParser.ts:1-22)
export const parseExternalPlaylistInfo = (text: string) => {
  // NetEase Music
  if (text.includes('music.163.com')) {
    const result = /id=(\d+)/.exec(text)
    if (result?.[1]) {
      return { id: result[1], source: 'netease' }
    }
  }
  
  // QQ Music
  if (text.includes('.qq.com')) {
    const result = /id=(\d+)/.exec(text)
    if (result?.[1]) {
      return { id: result[1], source: 'qq' }
    }
  }
  
  return null
}

​
Matching Process

BBPlayer uses an intelligent matching algorithm to find corresponding tracks on Bilibili.

​
How Matching Works

1

Fetch External Playlist

BBPlayer retrieves the complete playlist from the external service:
  • Track titles
  • Artist names
  • Album information
  • Track duration
  • Cover artwork
2

Search Bilibili

For each track, BBPlayer searches Bilibili using:
const keyword = `${track.title} ${track.artist}`
const results = await bilibiliApi.search(keyword)
The search intentionally does not use cookies to avoid personalized results that might reduce match accuracy.
3

Score Candidates

Each search result is scored based on:
  • Title similarity (Longest Common Subsequence algorithm)
  • Artist name match
  • Duration difference (within 10% tolerance)
  • Video properties (audio-only preferred)
// Scoring logic from apps/mobile/src/lib/services/externalPlaylistService.ts
const matchScore = calculateMatchScore({
  titleSimilarity: lcsScore(track.title, video.title),
  artistMatch: video.author.includes(track.artist),
  durationDiff: Math.abs(track.duration - video.duration),
  videoQuality: video.hasAudio && !video.hasVideo
})
4

Select Best Match

The candidate with the highest score above the confidence threshold is selected. If no match meets the threshold, the track is marked as “未匹配” (No match).

​
Match Quality Indicators

The import UI shows match confidence:
  • Score > 0.85
  • Very likely correct match
  • Title and artist closely match
  • Duration within 5% of original
  • Score 0.65 - 0.85
  • Probable match but verify manually
  • Some metadata differences
  • Consider alternative if available
  • Score 0.5 - 0.65
  • Weak match, likely incorrect
  • Significant metadata differences
  • Review and replace recommended
  • Score < 0.5 or no results
  • Track not available on Bilibili
  • Will be excluded from import
  • Manual search required

​
Review and Adjust Matches

Before finalizing the import, review all matched tracks.

​
Match Review Interface

The external playlist sync screen shows:
For each track:
  • Original: Track name from external service
  • Matched: Bilibili video title
  • Match score: Confidence indicator
  • Preview: Tap to verify it’s correct

​
Bulk Actions

Use bulk actions to quickly manage large playlists:
  • Select All Good Matches: Auto-select all high-confidence matches
  • Deselect No Matches: Remove all unmatched tracks
  • Re-match All Low Scores: Re-run matching for weak results

​
Saving Imported Playlist

Once satisfied with the matches, save the playlist to your library.
1

Configure Playlist Details

BBPlayer pre-fills:
  • Title: From original playlist
  • Description: From original playlist
  • Cover: From original playlist
You can edit any of these fields before saving.
2

Save as Local Playlist

Tap “保存” (Save). BBPlayer will:
  • Create artists in local database
  • Create track entries for all matched videos
  • Create the playlist
  • Add tracks to playlist in original order
// Save process (apps/mobile/src/lib/facades/syncExternalPlaylist.ts:36-161)
public saveMatchedPlaylist(
  playlistInfo: { title, coverUrl, description },
  matchResults: MatchResult[]
) {
  return db.transaction(async (tx) => {
    // 1. Create/find artists
    const artistsMap = await artistSvc.findOrCreateManyRemoteArtists(...)
    
    // 2. Create tracks
    const tracksMap = await trackSvc.findOrCreateManyTracks(...)
    
    // 3. Create playlist
    const playlistId = await playlistSvc.createPlaylist(...)
    
    // 4. Add tracks to playlist
    await playlistSvc.addManyTracksToLocalPlaylist(playlistId, trackIds)
    
    return playlistId
  })
}
3

Playlist Ready

The imported playlist now appears in your library and can be:
  • Played immediately
  • Edited (add/remove tracks)
  • Synced to BBPlayer Cloud
  • Downloaded for offline playback

​
Import Statistics

After import completion, BBPlayer displays:
  • Total tracks in original playlist
  • Successfully matched tracks
  • Match rate percentage
  • Failed matches count
  • Import duration
A match rate above 80% is considered excellent. Below 50% suggests the content may not be well-represented on Bilibili.

​
Advanced Matching Configuration

Customize matching behavior in Settings > Import:

​
Match Sensitivity

​
Search Options

  • Duration tolerance: ±5%, ±10%, or ±15%
  • Artist match weight: How much to prioritize artist name
  • Prefer audio-only: Favor audio-only videos over regular videos
  • Skip covers/live: Exclude cover versions and live performances

​
Worker-Based Processing

Large playlist imports use a background worker for better performance. 
// Playlist sync worker (apps/mobile/src/lib/workers/PlaylistSyncWorker.ts)
export class PlaylistSyncWorker {
  async processPlaylist(externalPlaylistId: string, source: 'netease' | 'qq') {
    // Fetch playlist metadata
    const playlist = await this.fetchExternalPlaylist(externalPlaylistId, source)
    
    // Match tracks in batches
    const batchSize = 10
    const results = []
    
    for (let i = 0; i < playlist.tracks.length; i += batchSize) {
      const batch = playlist.tracks.slice(i, i + batchSize)
      const batchResults = await Promise.all(
        batch.map(track => this.matchTrack(track))
      )
      results.push(...batchResults)
      
      // Report progress
      this.reportProgress(results.length, playlist.tracks.length)
    }
    
    return results
  }
}
Batch processing prevents UI freezing and provides real-time progress updates during large imports.

​
Troubleshooting

​
Import Gets Stuck

  • Check internet connection
  • Verify external service is accessible
  • Try a smaller playlist first
  • Restart the app and try again

​
Low Match Rate

1

Check Content Type

Some music genres are poorly represented on Bilibili:
  • Western pop music may have fewer matches
  • Chinese music generally matches better
  • Niche genres may require manual search
2

Adjust Settings

  • Increase duration tolerance
  • Lower match threshold
  • Disable artist name requirement
3

Manual Matching

For important tracks that didn’t match:
  • Search manually in BBPlayer
  • Add to playlist directly
  • Update match settings for future imports

​
”Playlist Not Found” Error

  • Verify the playlist is public (not private)
  • Check URL is correct and complete
  • Some playlists may be region-restricted
  • Try accessing in a web browser first

​
Duplicate Tracks After Import

  • BBPlayer detects existing tracks by unique key
  • If duplicates appear, they may be different versions
  • Use playlist cleanup tools to merge duplicates

​
Import Fails Midway

  • Progress is saved - you can resume
  • Check device storage space
  • Verify app has database write permission
  • Large playlists (>500 tracks) may timeout

​
Best Practices

For Optimal Import Results:
  1. Start Small: Test with a small playlist (10-20 tracks) first
  2. Review Matches: Always review before saving, especially for important playlists
  3. Use High-Quality Sources: Well-curated playlists match better
  4. Check Metadata: Playlists with accurate metadata improve matching
  5. Internet Connection: Use Wi-Fi for large imports
  6. Regular Updates: Re-sync periodically to catch new uploads

​
API Integration

Developers can use the external playlist service programmatically: 
import { externalPlaylistService } from '@/lib/services/externalPlaylistService'

// Match a single track
const result = await externalPlaylistService.matchSingleTrack({
  title: 'Song Title',
  artist: 'Artist Name',
  duration: 240  // seconds
})

if (result.isOk()) {
  const match = result.value
  console.log('Matched:', match.matchedVideo)
  console.log('Confidence:', match.confidence)
}

// Match entire playlist
const playlistResults = await externalPlaylistService.matchPlaylist(
  playlistId,
  'netease'  // or 'qq'
)

​
Future Enhancements

Planned features for playlist import:
  • Spotify integration: Import from Spotify playlists
  • Apple Music support: Connect with Apple Music library
  • Auto-sync: Automatically update imported playlists
  • Smart recommendations: Suggest Bilibili alternatives for no-match tracks
  • Batch import: Import multiple playlists simultaneously
  • Export matches: Save matching results for later use

Build docs developers (and LLMs) love

Get started for freeTalk to us