How QQ Music Mini‑Program Handles Audio Playback: Core Features, Bugs & Fixes

Core Features of QQ Music Mini Program

Open station

Friend card

Guide page (prompt users to log in with WeChat to QQ Music or trigger cold start)

Cold start

Card details (friend similarity, preferences, comments )

Song playback page (play/pause, lyric scroll, favorite, track switch, playback reporting, background magic color, adaptation)

Mini player (track switch, state sync)

Core Feature Implementation

Audio State Synchronization

Playback state synchronization cannot use the audio component; instead it relies on WeChat native playback components. Navigating with wx.navigateTo() keeps the current page alive, and returning triggers onShow (not onLoad), which is where state‑sync logic should run.

Song information and changes (playlist, play state, track switch, album art, title, artist, etc.) are stored in the Mini Program storage to enable data sharing across pages.

Lyric Scrolling

The audio API lacks an onTimeUpdate event, so a timer is used to render scrolling lyrics, which is not perfectly precise. WeChat plans to add onTimeUpdate support.

Background Color Magic

The app extracts a dominant hex color from the album cover, converts it to HSL, reduces saturation (S) and lightness (L) to soften the background, then converts it back to RGB.

Exception Handling

Handles missing or failed image loads, slow CGI responses in weak networks (shows loading spinner, hides after success, limits wx.showToast to 10 s), and reports network or logic errors with device info for later debugging.

Music Playback Control Bugs & Fixes

Android pause‑then‑play issue

Older Android WeChat versions check title and coverImgUrl when resuming; the bug was fixed by always passing these parameters.

iOS/Android pause‑then‑switch track

When pausing and then switching tracks, the old track may continue playing. The fix is to call wx.stopBackgroundAudio before invoking wx.playBackgroundAudio({dataUrl:'xxx'}).

Android sync playback state

When a song plays and a new page opens, wx.getBackgroundAudioPlayerState may return status 2 (no music) and mismatched URLs. The solution is to store the playback URL in storage and retrieve it for synchronization.

Mini Program Basics

Mina Framework

JS – logic layer development WXML – page layout WXSS – page styling

Logic Layer

The App() function registers a Mini Program. Parameters are passed as an object defining lifecycle callbacks.

Data in Page is read‑only; updates must use setData(), which performs a diff before rendering. setData payload cannot exceed 1024 KB.

View Layer

The system consists of a view thread (renders WXML/WXSS) and an app service thread (runs JS). The JS thread runs in jsCore, not in a WebView, so there is no global window object.

Module System

Common code is extracted into separate JS files and exported via module.exports or exports. Other files import them with require(path).

WXSS

Introduces rpx for responsive layout (750 rpx = screen width). Images must be network URLs or base64 because local resources cannot be accessed directly.

API Highlights

wx.request sends HTTPS requests. Data is stringified if not already a string. Default content-type is application/json; method names must be uppercase. Max concurrent requests: 5. referer is fixed to https://servicewechat.com/{appid}/{version}/page-frame.html. Timeout defaults to 60 s.

Music Playback wx.getBackgroundAudioPlayerState obtains playback status; wx.playBackgroundAudio plays a single background track. wx.pauseBackgroundAudio pauses, wx.seekBackgroundAudio seeks, and wx.stopBackgroundAudio stops (triggers wx.onBackgroundAudioStop).

Data Caching

Mini Programs provide a local storage API (no cookies or sessionStorage). It supports asynchronous and synchronous CRUD operations.

Device Info

Use wx.getSystemInfo() or wx.getSystemInfoSync() to obtain device details for UI adaptation and error reporting.

UI Interaction

wx.showToast

/ wx.hideToast for brief messages, wx.showModal for dialogs. Navigation: wx.navigateTo keeps the current page, wx.navigateBack returns; wx.redirectTo replaces the current page. A Mini Program can keep up to five pages open simultaneously.

Authentication

wx.login

obtains a login code, which can be exchanged for openid and session_key. wx.getUserInfo retrieves user data after login.