Skip to main content
BBPlayer’s download system enables offline listening with full metadata support, queue management, and audio file export capabilities.

​
Download System Architecture

Downloads are managed by the Orpheus native module, providing robust and efficient background downloading.

​
Core Features

  • Continue downloading even when app is closed
  • Automatic retry on network failures
  • Resume support for interrupted downloads
  • Download queue with concurrent task management
Downloaded files include:
  • Track title and artist
  • Album artwork
  • Duration and bitrate
  • Source information (BVID, CID)
  • Custom metadata for BBPlayer
  • Efficient file organization
  • Automatic cleanup of incomplete downloads
  • Storage space monitoring
  • Duplicate detection

​
Starting a Download

Download individual tracks or entire playlists directly from the app.

​
Download Single Track

1

Access Track Menu

From any track list (playlist, search results, etc.), tap the three-dot menu next to the track.
2

Select Download

Choose “下载” (Download) from the menu. The track is added to the download queue immediately.
3

Monitor Progress

A notification appears showing download progress. Access the full download manager from Settings > Downloads or the toolbar icon.

​
Download Playlist

1

Open Playlist Menu

From the playlist detail screen, tap the menu icon in the toolbar.
2

Select Download All

Choose “下载全部” (Download All). BBPlayer will:
  • Validate all tracks are available
  • Add them to the download queue
  • Start downloading concurrently
3

Batch Progress

View progress of all downloads in the download manager. Completed downloads appear in the “已下载” (Downloaded) tab.

​
Download Manager

The download manager (apps/mobile/src/app/download.tsx) provides comprehensive control over active and completed downloads.

​
Active Downloads View

Monitor in-progress downloads with real-time updates:
Each download task can be in one of several states:
  • Pending: Queued, waiting to start
  • Downloading: Actively downloading
  • Paused: Manually paused by user
  • Failed: Download error occurred
  • Completed: Successfully downloaded

​
Downloaded Content View

Access all completed downloads from the Downloaded screen: 
// Filter completed downloads (apps/mobile/src/app/downloaded.tsx:220-222)
const completedTasks = (allTasks ?? []).filter(
  (t) => t.state === DownloadState.COMPLETED,
)
Downloaded tracks can be played without an internet connection and include all metadata for a seamless offline experience.

​
Download Management Actions

1

Clear Completed

Remove all completed download records (files remain cached):
await Orpheus.clearUncompletedDownloadTasks()
2

Search Downloads

Use the search bar to filter by:
  • Track title
  • Artist name
  • Album name
3

Select Multiple

Long-press any item to enter selection mode, then:
  • Select all / invert selection
  • Delete selected
  • Export selected

​
Offline Playback

Downloaded tracks are seamlessly integrated into the playback system.

​
How It Works

When playing a track:
  1. Check if download exists locally
  2. If yes, use local file (no network required)
  3. If no, stream from Bilibili servers
This happens transparently - you don’t need to manually select offline mode.
BBPlayer detects offline status and:
  • Automatically uses downloaded files
  • Disables network-dependent features
  • Shows offline indicator in UI
  • Prevents streaming attempts
All track information is available offline:
  • Title, artist, album
  • Cover artwork (cached)
  • Lyrics (if previously fetched)
  • Duration and bitrate

​
Offline-Specific Features

  • Offline playlists: Filter playlists to show only downloaded tracks
  • Storage usage: View total space used by downloads
  • Download queue: Pre-download playlists before going offline

​
Audio Export

Export downloaded audio files to external storage (Android only).
Audio export is currently only available on Android due to platform file system limitations. iOS support is planned for future releases.

​
Export Process

1

Select Tracks to Export

In the Downloaded screen:
  • Tap Export icon to export all
  • Or enter selection mode to export specific tracks
2

Choose Destination

Select a directory using the Android document picker:
const directoryUri = await Orpheus.selectDirectory()
BBPlayer uses Android’s Storage Access Framework (SAF) for secure, user-controlled file access.
3

Export Progress

A modal displays export progress:
  • Files exported: X / Y
  • Current file name
  • Overall progress percentage
  • Success/failure status per file
4

Completion

Exported files include:
  • Audio in original format (usually AAC or M4A)
  • Embedded metadata (ID3 tags)
  • Cover artwork
  • Filename: {Artist} - {Title}.m4a

​
Export Modal Component

// Export progress modal (apps/mobile/src/components/modals/settings/ExportDownloadsProgressModal.tsx)
<ExportDownloadsProgressModal
  sheetRef={exportSheetRef}
  ids={selectedIds}
  destinationUri={targetDirectory}
/>
Features:
  • Real-time progress updates
  • Error handling per file
  • Cancel operation support
  • Success summary

​
Download Settings

Configure download behavior in Settings > General:

​
Network Settings

Control whether downloads can use mobile data:
  • Enabled: Download over any connection
  • Disabled: Wi-Fi only (recommended)
Downloads can consume significant data. Enable cellular downloads only if you have an unlimited plan.

​
Audio Quality

BBPlayer downloads the highest quality audio available from Bilibili, typically 320kbps AAC or FLAC when available.
Quality selection:
  • Auto: Highest available quality
  • High (320kbps): AAC 320kbps
  • Medium (192kbps): AAC 192kbps
  • Low (128kbps): AAC 128kbps (saves storage)

​
Storage Location

Downloads are stored in the app’s private cache directory: 
Android: /data/data/com.bbplayer/cache/downloads/
iOS: Library/Caches/downloads/
Files in cache may be cleared by the system when storage is low. For permanent storage, export files to external storage.

​
Download Queue Management

The download queue system manages concurrent downloads efficiently.

​
Queue Behavior

Downloads are processed in order:
  1. User-initiated single downloads (highest priority)
  2. Manual queue additions
  3. Batch playlist downloads
You can reorder the queue by dragging items in the download manager.
// Maximum concurrent downloads
const MAX_CONCURRENT = 3

// Queue processes next task when one completes
// Prevents overwhelming network and system resources
Failed downloads:
  • Remain in queue with error status
  • Show error reason (network, unavailable, permission)
  • Can be manually retried
  • Auto-retry if enabled in settings

​
Clearing Failed Downloads

Quickly remove all failed tasks: 
// Clear button in download manager (apps/mobile/src/app/download.tsx:72-77)
onClearAll={async () => {
  await Orpheus.clearUncompletedDownloadTasks()
  await queryClient.invalidateQueries({
    queryKey: orpheusQueryKeys.downloadTasks(),
  })
}}

​
Download API Reference

The Orpheus module provides programmatic download control:

​
Start Download

const downloadId = await Orpheus.startDownload({
  url: audioUrl,
  track: {
    title: 'Song Title',
    artist: 'Artist Name',
    artwork: coverUrl,
    duration: 240,
    ...metadata
  }
})

​
Control Downloads

// Pause download
await Orpheus.pauseDownload(downloadId)

// Resume paused download
await Orpheus.resumeDownload(downloadId)

// Cancel and remove
await Orpheus.removeDownload(downloadId)

// Retry failed download
await Orpheus.retryDownload(downloadId)

​
Query Downloads

// Get all download tasks
const tasks = await Orpheus.getAllDownloadTasks()

// Get completed downloads only
const completed = tasks.filter(t => t.state === DownloadState.COMPLETED)

// Check if track is downloaded
const isDownloaded = await Orpheus.isTrackDownloaded(trackId)

​
Select Directory (Android)

// Open Android SAF directory picker
const uri = await Orpheus.selectDirectory()
// Returns: content://com.android.externalstorage.documents/tree/...

​
Troubleshooting

​
Downloads Keep Failing

1

Check Network

  • Verify internet connection
  • Try switching between Wi-Fi and cellular
  • Check if Bilibili is accessible
2

Check Storage

  • Ensure sufficient free space
  • Clear app cache if needed
  • Check storage permissions
3

Check Authentication

  • Verify Bilibili login is valid
  • Re-login if session expired
  • Some tracks require authentication

​
Download Stuck at 0%

  • Kill and restart the app
  • Remove and re-add the download
  • Check if track is still available on Bilibili
  • Verify audio URL hasn’t expired

​
Export Fails on Android

  • Grant storage permission when prompted
  • Ensure destination directory is writable
  • Check available space on external storage
  • Try selecting a different directory

​
Downloaded Files Not Playing

  • Verify download completed successfully (100%)
  • Check file integrity in download manager
  • Re-download if file is corrupted
  • Report issue with track BVID for investigation

​
High Storage Usage

1

View Storage Details

Settings > General > Storage shows breakdown of space usage.
2

Delete Unused Downloads

  • Enter selection mode in Downloaded tab
  • Select tracks to remove
  • Tap delete to free up space
3

Export and Delete

  • Export important tracks to external storage
  • Delete from app cache
  • Re-download when needed

​
Performance Tips

For Best Download Performance:
  • Download over Wi-Fi when possible
  • Keep app in foreground during large downloads
  • Don’t exceed 3 concurrent downloads
  • Close other apps to free up resources
  • Ensure battery optimization is disabled for BBPlayer

​
Battery Optimization

On Android, disable battery optimization to prevent download interruption:
  1. Go to Android Settings > Apps > BBPlayer
  2. Battery > Battery optimization
  3. Select “Don’t optimize”
This ensures downloads continue even when the screen is off.

Build docs developers (and LLMs) love

Get started for freeTalk to us