Diagnostic logs

Some playback problems only show up on a real device in real use: a car connection, a lock screen, a phone that has been asleep for twenty minutes. For those, the library can write diagnostic lines to the device's system log, where they stay on the phone and can be exported later, including from a TestFlight or App Store build.

Turn them on

import { getTrackPlayer } from 'react-native-queue-player';

await getTrackPlayer().configure({
  enableDiagnosticLogs: true,
});

The option is read at configure(). It is off by default. A common pattern is to tie it to a hidden or advanced setting in your app, so a tester can turn it on, reproduce a problem and send you the logs.

iOS only today: Android accepts the option and writes nothing yet.

What gets logged

Lines go to the unified log under subsystem com.margelo.nitro.queueplayer, one category per area:

Category	Contents
NowPlaying	Every write to the lock screen / CarPlay Now Playing information: what triggered it, how long it waited before running, the app state, the queue entry the write belongs to (item=, the first 8 characters of the id the library publishes as the item's identifier), rate, position, and whether the artwork was the placeholder or a resolved image. Skipped writes (including resolved artwork dropped because a later track change was already published, reason=otherItem), artwork loads, and the writes made while a cast session owns Now Playing are logged too, as is each time the system asks for the artwork image and at what size.
AudioSession	Category changes, activation (with the output route) and deactivation, interruptions (type, options, reason), route changes (reason, previous and current outputs), media services lost or reset, and on iOS 27 and later the system's own session activation, deactivation (source and interruption reason) and resumption recommendations.
RemoteCommand	Each lock screen, Control Center, CarPlay or headphone command as it arrives (or is rejected), and when the library registers or removes its command handlers.
Player	configure() and destroy(), each state change with its reason, each track change, and each call to the playback engine's play, pause and stop.
CarPlay	CarPlay connecting and disconnecting, the CarPlay scene entering and leaving the foreground and becoming active or inactive, and each template appearing and disappearing.
App	The app entering the background and returning to the foreground.

Lines are written at the system's default level, which iOS keeps in its on-disk log store, and are readable after export. They carry state, timings and reasons only: never track titles, artists, URLs or your own ids.

Export the logs from a device

The system log keeps recent history, so export soon after the problem happens. Note the time it happened; you will filter on it.

From the phone, no Mac needed (sysdiagnose)

This works for any build, including TestFlight and App Store builds.

1. Press and release both volume buttons and the side button at the same time. Keep it brief: holding them for a second or more locks the phone or starts Emergency SOS instead. The phone vibrates briefly when the capture starts.
2. Wait up to ten minutes while the capture is collected.
3. Open Settings → Privacy & Security → Analytics & Improvements → Analytics Data and find the file whose name starts with sysdiagnose_ and matches the time you pressed the buttons.
4. Share it to a Mac with AirDrop, or connect the phone and copy it with Finder.

On the Mac, unpack the archive and read the library's lines from the log archive inside it:

tar -xzf sysdiagnose_*.tar.gz
log show --archive sysdiagnose_*/system_logs.logarchive \
  --predicate 'subsystem == "com.margelo.nitro.queueplayer"' \
  --start "2026-10-10 17:40:00" --end "2026-10-10 18:00:00"

With the phone connected to a Mac

With the phone paired to the Mac and connected by cable:

sudo log collect --device --start "2026-10-10 17:40:00" --output rnqp.logarchive
log show --archive rnqp.logarchive --predicate 'subsystem == "com.margelo.nitro.queueplayer"'

--device-name "<phone name>" picks a specific phone when more than one is connected. The archive also opens in Console.app, where you can filter on the subsystem and see the library's lines next to the system's own.

To watch live instead, open Console.app with the phone connected, select the phone, start streaming, and filter on subsystem:com.margelo.nitro.queueplayer.

Sending logs with a bug report

Include the time the problem happened and what was on screen. The library's lines are most useful next to the system's own around the same time, so when you can, send the whole system_logs.logarchive (or the sysdiagnose) rather than only the filtered output.