A cross platform Audiobookshelf client for Android and iOS
Dart
import 'dart:async';
import 'dart:io';
import 'package:flutter/foundation.dart';
import 'package:flutter/services.dart';
import 'package:flutter_carplay/flutter_carplay.dart';
import 'android_auto_service.dart';
import 'api_service.dart';
import 'audio_player_service.dart';
import 'carplay_image_url.dart';
import 'server_backend.dart';
/// Manages Apple CarPlay browse tree and playback integration.
/// Mirrors the Android Auto layout: 3 tabs (Continue, Library, Downloads)
/// with hierarchical drilling into books/series/authors and podcasts.
class CarPlayService {
static final CarPlayService _instance = CarPlayService._();
factory CarPlayService() => _instance;
CarPlayService._();
final _autoService = AndroidAutoService();
final _flutterCarplay = FlutterCarplay();
/// Bridges CarPlay Now Playing button taps to/from native. The buttons live
/// only on CPNowPlayingTemplate, so the iOS lock screen is never affected.
static const _nowPlayingChannel = MethodChannel('com.absorb.carplay');
double _lastPushedSpeed = -1;
bool _bannerShowing = false;
Timer? _bannerDismissTimer;
bool _initialized = false;
bool _connected = false;
DateTime? _lastRootBuilt;
CPTabBarTemplate? _rootTemplate;
Future<void>? _inFlightBuild;
void init() {
if (!Platform.isIOS || _initialized) return;
_initialized = true;
_flutterCarplay.addListenerOnConnectionChange(_onConnectionChange);
_nowPlayingChannel.setMethodCallHandler(_handleNativeCall);
// Keep the CarPlay speed button label in sync with rate changes from
// anywhere (the phone speed sheet, a per-book default, etc.).
AudioPlayerService().addListener(_onPlayerChanged);
debugPrint('[CarPlay] Initialized');
// Re-render the root template when the background server refresh
// completes. AutoBrowse.refresh() returns immediately after downloads
// are populated and continues the server fetch in the background;
// this hook is how we know to swap the downloads-only tree for the
// full one (or the other way for offline → online recovery).
AndroidAutoService.onServerDataChanged = () {
if (!_initialized || !_connected || _rootTemplate == null) return;
// _connectAndRender awaits its own refresh() which fires this callback
// mid-flight; without this guard both paths call setRootTemplate within
// ~0ms and CarPlay renders the tabs blank until the user backgrounds
// and reopens the app.
if (_inFlightBuild != null) {
debugPrint('[CarPlay] onServerDataChanged - skipped (build in flight)');
return;
}
if (_lastRootBuilt != null &&
DateTime.now().difference(_lastRootBuilt!) < const Duration(milliseconds: 500)) {
debugPrint('[CarPlay] onServerDataChanged - skipped (built ${DateTime.now().difference(_lastRootBuilt!).inMilliseconds}ms ago)');
return;
}
debugPrint('[CarPlay] onServerDataChanged - rebuilding root template');
refreshTemplates();
};
unawaited(_restoreConnectionState());
}
Future<void> _restoreConnectionState() async {
try {
if (await FlutterCarplay.isConnected && _initialized && !_connected) {
_onConnectionChange(ConnectionStatusTypes.connected);
}
} catch (e) {
debugPrint('[CarPlay] Connection state check failed: $e');
}
}
void dispose() {
_connected = false;
_flutterCarplay.removeListenerOnConnectionChange();
AudioPlayerService().removeListener(_onPlayerChanged);
_bannerDismissTimer?.cancel();
}
void _onConnectionChange(ConnectionStatusTypes status) {
debugPrint('[CarPlay] Connection status: $status');
if (status == ConnectionStatusTypes.disconnected) {
_connected = false;
_rootTemplate = null;
_lastRootBuilt = null;
_bannerDismissTimer?.cancel();
_bannerShowing = false;
return;
}
if (status != ConnectionStatusTypes.connected) return;
if (_connected) return;
_connected = true;
unawaited(_maybeAutoplayOnConnect());
_connectAndRender();
}
/// GH #371 (CarPlay side): opt-in autoplay when the car connects with
/// nothing loaded. Unlike Android Auto there's an explicit connection
/// event, so no browse-stamp heuristics - the _connected edge above is the
/// once-per-connection gate. A loaded book means the session is alive and
/// a resume belongs to the user (or the head unit's own play command), and
/// it keeps a deliberate pause from being undone by a reconnect.
Future<void> _maybeAutoplayOnConnect() async {
try {
final player = AudioPlayerService();
if (player.hasBook) return;
if (!await PlayerSettings.getAutoplayOnCarConnect()) return;
// The connect event can arrive during a cold launch in the car - let
// init settle before starting audio.
await Future.delayed(const Duration(milliseconds: 1500));
if (!_connected) return;
if (player.hasBook || player.isPlaying) return;
final restore = AudioPlayerService.onColdStartPlayRequested;
if (restore == null) return;
debugPrint('[AutoPlay] CarPlay connected - resuming last played');
await restore();
} catch (e) {
debugPrint('[AutoPlay] CarPlay autoplay failed: $e');
}
}
Future<void> _connectAndRender() async {
if (!_connected) return;
// Make sure data is loaded before rendering so the first template the
// user sees has real content.
//
// We avoid calling setRootTemplate twice (once empty, once full) because
// the flutter_carplay native side appears to leave the first template
// visible and the second call doesn't re-render. Same for
// updateTabBarTemplates - it updates the cached template but doesn't
// refresh the displayed UI and (worse) breaks tap routing on the new
// items. So we wait, then setRootTemplate once with full data.
try {
await _autoService.refresh();
} catch (e) {
debugPrint('[CarPlay] Pre-render refresh failed: $e');
}
if (!_connected) return;
await _setRootTemplate(label: 'on-connect');
}
/// Clear cache and rebuild templates (e.g. on account switch).
Future<void> clearAndRefresh() async {
if (!_initialized || !_connected) return;
await _autoService.refresh(force: true);
if (!_connected) return;
await _setRootTemplate(label: 'clear-and-refresh');
}
/// Refresh CarPlay templates (e.g. after download completes).
Future<void> refreshTemplates() async {
if (!_initialized || !_connected) return;
await _setRootTemplate(label: 'refresh-templates');
}
// ─── Root template ──────────────────────────────────────────────────
Future<List<CPListTemplate>> _buildTabs() async {
final downloadsTab = await _buildDownloadsTab();
// When the server is unreachable, Continue / New / Library are empty
// anyway (we skip the server fetch). Drop them so CarPlay opens
// straight into the user's downloads instead of showing three empty
// tabs they have to swipe past.
if (AudioPlayerService().knownOffline) {
return [downloadsTab];
}
// Cold start race: knownOffline defaults to false and only flips after
// the auth ping fails (~15s). If CarPlay connects before then with no
// server data loaded yet, Continue/New/Library would render as empty
// tabs and the user lands on a blank Continue tab. Skip any tab that
// has nothing to show; onServerDataChanged will rebuild once data
// arrives.
final tabs = <CPListTemplate>[];
if (_autoService.continueListening.isNotEmpty) {
tabs.add(await _buildContinueTab());
}
if (_autoService.recentlyAdded.isNotEmpty) {
tabs.add(await _buildRecentlyAddedTab());
}
if (_autoService.libraries.isNotEmpty) {
tabs.add(await _buildLibraryTab());
}
tabs.add(downloadsTab);
return tabs;
}
Future<void> _setRootTemplate({String label = ''}) async {
if (!_connected) return;
// Coalesce concurrent calls. If a build is already in flight, await it
// instead of starting a second one - two setRootTemplate invocations
// racing within the same microtask leave CarPlay rendering blank tabs.
if (_inFlightBuild != null) {
debugPrint('[CarPlay] _setRootTemplate ($label) - awaiting in-flight build');
return _inFlightBuild;
}
final fut = _doSetRootTemplate(label: label);
_inFlightBuild = fut;
try {
await fut;
} finally {
_inFlightBuild = null;
}
}
Future<void> _doSetRootTemplate({required String label}) async {
final tabs = await _buildTabs();
if (!_connected) return;
final root = CPTabBarTemplate(templates: tabs);
_rootTemplate = root;
await FlutterCarplay.setRootTemplate(rootTemplate: root, animated: false);
if (!_connected) return;
// Without this the native side may not register onPress callbacks on
// the new list items, leaving taps stuck on an infinite spinner.
await _flutterCarplay.forceUpdateRootTemplate();
_lastRootBuilt = DateTime.now();
debugPrint('[CarPlay] Root template set ($label)'
' continue=${_autoService.continueListening.length}'
' downloads=${_autoService.downloaded.length}'
' libraries=${_autoService.libraries.length}');
// Configure the Now Playing buttons after the root template is built.
await _configureNowPlayingButtons();
}
// ─── Now Playing custom buttons ─────────────────────────────────────
/// Ask the native side to (re)attach the custom buttons to
/// CPNowPlayingTemplate.shared.
Future<void> _configureNowPlayingButtons() async {
if (!_connected) return;
try {
final speed = AudioPlayerService().speed;
_lastPushedSpeed = speed;
await _nowPlayingChannel
.invokeMethod('setupNowPlayingButtons', {'speed': speed});
} catch (e) {
debugPrint('[CarPlay] setupNowPlayingButtons failed: $e');
}
}
/// Refresh the CarPlay speed button when the rate changes anywhere.
void _onPlayerChanged() {
if (!_connected) return;
final speed = AudioPlayerService().speed;
if ((speed - _lastPushedSpeed).abs() < 0.001) return;
_configureNowPlayingButtons();
}
/// Briefly confirm a saved bookmark. CarPlay has no toast, so we present an
/// auto-dismissing modal alert (the closest thing to a banner it offers). The
/// OK action lets the driver dismiss early; otherwise it clears itself.
Future<void> _showBookmarkBanner() async {
if (!_connected) return;
try {
_bannerDismissTimer?.cancel();
if (_bannerShowing) {
await FlutterCarplay.popModal();
_bannerShowing = false;
}
if (!_connected) return;
await FlutterCarplay.showAlert(
template: CPAlertTemplate(
titleVariants: const ['Bookmark added'],
actions: [
CPAlertAction(
title: 'OK',
onPress: () {
_bannerDismissTimer?.cancel();
_bannerShowing = false;
if (_connected) FlutterCarplay.popModal();
},
),
],
),
);
_bannerShowing = true;
_bannerDismissTimer = Timer(const Duration(milliseconds: 1800), () {
if (!_connected || !_bannerShowing) return;
_bannerShowing = false;
FlutterCarplay.popModal();
});
} catch (e) {
debugPrint('[CarPlay] bookmark banner failed: $e');
}
}
/// Route a Now Playing button tap from native into the audio handler's
/// customAction, which owns the chapter/speed/bookmark logic.
Future<dynamic> _handleNativeCall(MethodCall call) async {
if (!_connected || call.method != 'carPlayButton') return null;
final action = (call.arguments as Map?)?['action'] as String?;
if (action == null) return null;
debugPrint('[CarPlay] Now Playing button: $action');
final result = await AudioPlayerService.handler?.customAction(action);
if (action == 'bookmark' && result == true) {
await _showBookmarkBanner();
}
return null;
}
// ─── Continue Listening tab ─────────────────────────────────────────
Future<CPListTemplate> _buildContinueTab() async {
final api = await _autoService.getApi();
final entries = _autoService.continueListening;
final items = entries.map((e) => _playableListItem(e, api)).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: 'Continue',
systemIcon: 'play.circle.fill',
);
}
// ─── Recently Added tab ────────────────────────────────────────────
Future<CPListTemplate> _buildRecentlyAddedTab() async {
final api = await _autoService.getApi();
final entries = _autoService.recentlyAdded;
final items = entries.map((e) => _playableListItem(e, api)).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: 'New',
systemIcon: 'sparkles',
);
}
// ─── Library tab ────────────────────────────────────────────────────
Future<CPListTemplate> _buildLibraryTab() async {
final libs = _autoService.libraries;
// Single library: skip picker, show sub-categories or shows directly
if (libs.length == 1) {
final lib = libs.first;
if (lib.isPodcast) {
return _buildPodcastShowsList(lib.id, lib.name);
}
return _buildBookSubCategories(lib.id, 'Library');
}
// Multiple libraries: show library picker
final items = libs.map((lib) {
return CPListItem(
text: lib.name,
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
if (lib.isPodcast) {
final template = await _buildPodcastShowsList(lib.id, lib.name);
_pushTemplate(template);
} else {
final template = await _buildBookSubCategories(lib.id, lib.name);
_pushTemplate(template);
}
complete();
},
);
}).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: 'Library',
systemIcon: 'books.vertical.fill',
);
}
// ─── Downloads tab ──────────────────────────────────────────────────
Future<CPListTemplate> _buildDownloadsTab() async {
final api = await _autoService.getApi();
final entries = _autoService.downloaded;
final items = entries.map((e) => _playableListItem(e, api)).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: 'Downloads',
systemIcon: 'arrow.down.circle.fill',
);
}
// ─── Book library sub-categories ───────────────────────────────────
Future<CPListTemplate> _buildBookSubCategories(String libraryId, String title) async {
final items = [
CPListItem(
text: 'Books',
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
final template = await _buildBooksList(libraryId);
_pushTemplate(template);
complete();
},
),
CPListItem(
text: 'Series',
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
final template = await _buildSeriesList(libraryId);
_pushTemplate(template);
complete();
},
),
CPListItem(
text: 'Authors',
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
final template = await _buildAuthorsList(libraryId);
_pushTemplate(template);
complete();
},
),
CPListItem(
text: 'Collections',
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
final template = await _buildGroupList(
title: 'Collections',
icon: 'square.stack.fill',
groups: await _autoService.fetchCollectionsData(libraryId),
entries: _autoService.fetchCollectionBooksData,
);
_pushTemplate(template);
complete();
},
),
if (!ServerBackend.active.isBookOrbit)
CPListItem(
text: 'Playlists',
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
final template = await _buildGroupList(
title: 'Playlists',
icon: 'music.note.list',
groups: await _autoService.fetchPlaylistsData(libraryId),
entries: _autoService.fetchPlaylistItemsData,
);
_pushTemplate(template);
complete();
},
),
];
return CPListTemplate(
sections: [CPListSection(items: items)],
title: title,
systemIcon: 'books.vertical',
);
}
// ─── Books list ────────────────────────────────────────────────────
/// CarPlay books browse. Unlike Android Auto, CarPlay caps the navigation
/// stack (~5 pushed templates), so a recursive letter drilldown (T -> Th ->
/// The -> ...) pushes too deep and iOS kills the app. Instead we show ONE
/// flat level of letter/prefix buckets (each <= bucketThreshold) and then
/// the book list - a fixed depth of two pushes.
Future<CPListTemplate> _buildBooksList(String libraryId) async {
final api = await _autoService.getApi();
final sorted = await _autoService.fetchSortedBooks(libraryId);
final all = sorted.books;
// Small library: skip the bucket level, list the books directly.
if (all.length <= AndroidAutoService.bucketThreshold) {
final items = all.map((e) => _playableListItem(e, api)).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: 'Books',
systemIcon: 'book.fill',
);
}
final buckets = _autoService.flattenedBookBuckets(all, sort: sorted.sort);
final items = buckets.map((b) {
return CPListItem(
text: b.prefix.isEmpty ? '#' : b.prefix,
detailText: '${b.count}',
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
final template = await _buildBooksLeaf(libraryId, b.prefix);
_pushTemplate(template);
complete();
},
);
}).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: 'Books',
systemIcon: 'book.fill',
);
}
/// Leaf book list for one flat bucket [prefix].
Future<CPListTemplate> _buildBooksLeaf(String libraryId, String prefix) async {
final api = await _autoService.getApi();
final sorted = await _autoService.fetchSortedBooks(libraryId);
final books =
_autoService.booksForPrefix(sorted.books, prefix, sort: sorted.sort);
final items = books.map((e) => _playableListItem(e, api)).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: prefix.isEmpty ? 'Books' : prefix,
systemIcon: 'book.fill',
);
}
/// Collections or playlists: a list of groups, each opening its books.
Future<CPListTemplate> _buildGroupList({
required String title,
required String icon,
required List<({String id, String name, int count})> groups,
required Future<List<AutoBookEntry>> Function(String id) entries,
}) async {
final items = groups.map((g) {
return CPListItem(
text: g.name,
detailText: '${g.count}',
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
final api = await _autoService.getApi();
final books = await entries(g.id);
_pushTemplate(CPListTemplate(
sections: [
CPListSection(
items: books.map((e) => _playableListItem(e, api)).toList()),
],
title: g.name,
systemIcon: icon,
));
complete();
},
);
}).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: title,
systemIcon: icon,
);
}
// ─── Series list ───────────────────────────────────────────────────
Future<CPListTemplate> _buildSeriesList(String libraryId) async {
final seriesData = await _autoService.fetchLibrarySeriesData(libraryId);
final items = seriesData.map((s) {
return CPListItem(
text: s.name,
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
final template = await _buildSeriesBooks(s.id, libraryId, s.name);
_pushTemplate(template);
complete();
},
);
}).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: 'Series',
systemIcon: 'rectangle.stack.fill',
);
}
Future<CPListTemplate> _buildSeriesBooks(String seriesId, String libraryId, String title) async {
final api = await _autoService.getApi();
final entries = await _autoService.fetchSeriesBooksData(seriesId, libraryId);
final items = entries.map((e) => _playableListItem(e, api)).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: title,
systemIcon: 'rectangle.stack.fill',
);
}
// ─── Authors list ──────────────────────────────────────────────────
Future<CPListTemplate> _buildAuthorsList(String libraryId) async {
final authorsData = await _autoService.fetchLibraryAuthorsData(libraryId);
final items = authorsData.map((a) {
return CPListItem(
text: a.name,
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
final template = await _buildAuthorBooks(a.id, libraryId, a.name);
_pushTemplate(template);
complete();
},
);
}).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: 'Authors',
systemIcon: 'person.2.fill',
);
}
Future<CPListTemplate> _buildAuthorBooks(String authorId, String libraryId, String title) async {
final api = await _autoService.getApi();
final entries = await _autoService.fetchAuthorBooksData(authorId, libraryId);
final items = entries.map((e) => _playableListItem(e, api)).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: title,
systemIcon: 'person.fill',
);
}
// ─── Podcast shows ─────────────────────────────────────────────────
Future<CPListTemplate> _buildPodcastShowsList(String libraryId, String title) async {
final showsData = await _autoService.fetchPodcastShowsData(libraryId);
final items = showsData.map((s) {
return CPListItem(
text: s.title,
image: safeCarPlayImageUrl(s.coverUrl),
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
final template = await _buildShowEpisodes(s.id, libraryId, s.title);
_pushTemplate(template);
complete();
},
);
}).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: title,
systemIcon: 'mic.fill',
);
}
Future<CPListTemplate> _buildShowEpisodes(String showId, String libraryId, String title) async {
final api = await _autoService.getApi();
final entries = await _autoService.fetchShowEpisodesData(showId, libraryId);
final items = entries.map((e) => _playableListItem(e, api)).toList();
return CPListTemplate(
sections: [CPListSection(items: items)],
title: title,
systemIcon: 'mic.fill',
);
}
// ─── Helpers ───────────────────────────────────────────────────────
/// Build a playable CPListItem from an AutoBookEntry. Recently-added
/// podcast shows aren't directly playable, so build a browseable item that
/// drills into the show's episodes.
CPListItem _playableListItem(AutoBookEntry entry, ApiService? api) {
final coverItemId = entry.showId ?? entry.id;
// Downloaded books: file:// URL (already mtime-busted in _refreshDownloaded).
// Streaming: ?ts= the server updatedAt so iOS refetches after a cover change.
final entryUrl = entry.coverUrl;
final ts = AndroidAutoService.coverTsFor(coverItemId);
final rawCoverUrl = (entryUrl != null && entryUrl.startsWith('file://'))
? entryUrl
: api?.getCoverUrl(coverItemId, updatedAt: ts);
final coverUrl = safeCarPlayImageUrl(rawCoverUrl);
final isPodcastShow = entry.mediaType == 'podcast' &&
entry.episodeId == null &&
entry.libraryId != null &&
entry.libraryId!.isNotEmpty;
if (isPodcastShow) {
return CPListItem(
text: entry.title,
detailText: entry.author.isNotEmpty ? entry.author : null,
image: coverUrl,
accessoryType: CPListItemAccessoryTypes.disclosureIndicator,
onPress: (complete, self) async {
final template = await _buildShowEpisodes(
entry.id, entry.libraryId!, entry.title);
_pushTemplate(template);
complete();
},
);
}
final mediaId = (entry.episodeId != null && entry.showId != null)
? AutoMediaIds.itemId('${entry.showId}-${entry.episodeId}')
: AutoMediaIds.itemId(entry.id);
return CPListItem(
text: entry.title,
detailText: entry.author.isNotEmpty ? entry.author : null,
image: coverUrl,
playbackProgress: _playbackProgress(entry),
onPress: (complete, self) {
_playItem(mediaId);
complete();
},
);
}
double _playbackProgress(AutoBookEntry entry) {
if (entry.currentTime == null || entry.duration <= 0) return 0;
return (entry.currentTime! / entry.duration).clamp(0.0, 1.0);
}
void _pushTemplate(CPListTemplate template) {
if (!_connected) return;
FlutterCarplay.push(template: template);
}
void _playItem(String mediaId) {
debugPrint('[CarPlay] Playing: $mediaId');
// Call the handler directly. The static AudioService.playFromMediaId is a
// deprecated compat shim wired only in the old AudioService.start() flow;
// with the modern AudioService.init() it routes to a no-op BaseAudioHandler.
AudioPlayerService.handler?.playFromMediaId(mediaId);
// Jump straight to Now Playing on tap, like the native apps, instead of
// making the user find the Now Playing button. pushIfNotExist on the native
// side means it's a no-op if Now Playing is already on screen.
if (_connected) FlutterCarplay.showSharedNowPlaying();
}
}