Skip to content

A cross platform Audiobookshelf client for Android and iOS

Dart

Add streaming disk cache and fix large audiobook playback

Nathan Poulsone488ee58a161
diff --git a/android/app/src/main/AndroidManifest.xml b/android/app/src/main/AndroidManifest.xml
index 7ded2f48..74914155 100644
--- a/android/app/src/main/AndroidManifest.xml
+++ b/android/app/src/main/AndroidManifest.xml
@@ -17,7 +17,7 @@
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" tools:node="remove"/>
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" tools:node="remove"/>
- <application android:label="Absorb" android:name="${applicationName}" android:icon="@mipmap/ic_launcher" android:usesCleartextTraffic="true">
+ <application android:label="Absorb" android:name="${applicationName}" android:icon="@mipmap/ic_launcher" android:usesCleartextTraffic="true" android:largeHeap="true">
<activity android:name=".MainActivity" android:exported="true" android:launchMode="singleTop" android:taskAffinity="" android:theme="@style/LaunchTheme" android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode" android:hardwareAccelerated="true" android:windowSoftInputMode="adjustResize">
<meta-data android:name="io.flutter.embedding.android.NormalTheme" android:resource="@style/NormalTheme"/>
diff --git a/lib/screens/settings_screen.dart b/lib/screens/settings_screen.dart
index 032f2499..4826ab29 100644
--- a/lib/screens/settings_screen.dart
+++ b/lib/screens/settings_screen.dart
@@ -7,6 +7,7 @@ import 'package:permission_handler/permission_handler.dart';
import 'package:file_picker/file_picker.dart';
import 'package:url_launcher/url_launcher.dart';
import 'package:package_info_plus/package_info_plus.dart';
+import 'package:just_audio/just_audio.dart' show AudioPlayer;
import '../providers/auth_provider.dart';
import '../providers/library_provider.dart';
import '../services/audio_player_service.dart';
@@ -56,6 +57,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
bool _loggingEnabled = false;
bool _fullScreenPlayer = false;
String _themeMode = 'dark';
+ int _streamingCacheSizeMb = 0;
bool _loaded = false;
String _downloadLocationLabel = 'App Internal Storage (Default)';
int _totalDownloadSizeBytes = 0;
@@ -124,6 +126,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
DownloadService.getDeviceStorage(), // 26
AutoSleepSettings.load(), // 27
PackageInfo.fromPlatform(), // 28
+ PlayerSettings.getStreamingCacheSizeMb(), // 29
]);
final s = results[0] as AutoRewindSettings;
final speed = results[1] as double;
@@ -154,6 +157,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
final deviceStorage = results[26] as Map<String, int>?;
final autoSleep = results[27] as AutoSleepSettings;
final pkgInfo = results[28] as PackageInfo;
+ final cacheSizeMb = results[29] as int;
if (mounted) setState(() {
_rewindSettings = s;
_defaultSpeed = speed;
@@ -187,6 +191,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
}
_autoSleepSettings = autoSleep;
_appVersion = pkgInfo.version;
+ _streamingCacheSizeMb = cacheSizeMb;
_loaded = true;
});
}
@@ -1223,6 +1228,52 @@ class _SettingsScreenState extends State<SettingsScreen> {
onTap: () => Navigator.push(context,
MaterialPageRoute(builder: (_) => const DownloadsScreen())),
),
+ const Divider(height: 1, indent: 16, endIndent: 16),
+ Padding(
+ padding: const EdgeInsets.symmetric(horizontal: 16),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ const SizedBox(height: 12),
+ Text('Streaming cache', style: tt.bodyMedium?.copyWith(color: cs.onSurface)),
+ const SizedBox(height: 4),
+ Text(
+ _streamingCacheSizeMb == 0
+ ? 'Off — audio is streamed without caching'
+ : '$_streamingCacheSizeMb MB — recently streamed audio is cached to disk',
+ style: tt.bodySmall?.copyWith(color: cs.onSurfaceVariant)),
+ const SizedBox(height: 8),
+ SizedBox(width: double.infinity, child: SegmentedButton<int>(
+ segments: const [
+ ButtonSegment(value: 0, label: Text('Off')),
+ ButtonSegment(value: 128, label: Text('128 MB')),
+ ButtonSegment(value: 256, label: Text('256 MB')),
+ ButtonSegment(value: 512, label: Text('512 MB')),
+ ],
+ selected: {_streamingCacheSizeMb},
+ onSelectionChanged: (v) {
+ setState(() => _streamingCacheSizeMb = v.first);
+ PlayerSettings.setStreamingCacheSizeMb(v.first);
+ },
+ )),
+ if (_streamingCacheSizeMb > 0) ...[
+ const SizedBox(height: 8),
+ TextButton.icon(
+ icon: const Icon(Icons.delete_sweep_outlined, size: 18),
+ label: const Text('Clear cache'),
+ onPressed: () async {
+ await AudioPlayer.clearStreamingCache();
+ if (mounted) {
+ ScaffoldMessenger.of(context).showSnackBar(
+ const SnackBar(content: Text('Streaming cache cleared')));
+ }
+ },
+ ),
+ ],
+ const SizedBox(height: 8),
+ ],
+ ),
+ ),
],
),
const SizedBox(height: 16),
diff --git a/lib/services/api_service.dart b/lib/services/api_service.dart
index bf4417c3..6a76fa9c 100644
--- a/lib/services/api_service.dart
+++ b/lib/services/api_service.dart
@@ -410,34 +410,36 @@ class ApiService {
/// Start a playback session for a library item.
/// POST /api/items/:id/play
/// Returns the full session object including audioTracks with contentUrl.
- Future<Map<String, dynamic>?> startPlaybackSession(String itemId, {String? episodeId}) async {
+ Future<Map<String, dynamic>?> startPlaybackSession(String itemId, {String? episodeId, bool forceDirectPlay = false, bool forceTranscode = false, double? startOffset}) async {
try {
final epPath = episodeId != null ? '/$episodeId' : '';
final url = '$_cleanBaseUrl/api/items/$itemId/play$epPath';
- debugPrint('[ABS] Starting playback session: POST $url');
+ debugPrint('[ABS] Starting playback session: POST $url (forceDirectPlay: $forceDirectPlay, forceTranscode: $forceTranscode)');
+ final body = <String, dynamic>{
+ 'deviceInfo': {
+ 'clientName': 'Absorb',
+ 'clientVersion': appVersion,
+ 'deviceId': deviceId,
+ 'deviceName': '${deviceManufacturer.isNotEmpty ? "$deviceManufacturer " : ""}$deviceModel'.trim(),
+ 'manufacturer': deviceManufacturer,
+ 'model': deviceModel,
+ },
+ 'forceDirectPlay': forceDirectPlay,
+ 'forceTranscode': forceTranscode,
+ 'mediaPlayer': 'unknown',
+ 'supportedMimeTypes': [
+ 'audio/flac',
+ 'audio/mpeg',
+ 'audio/mp4',
+ 'audio/ogg',
+ 'audio/aac',
+ ],
+ };
+ if (startOffset != null && startOffset > 0) body['startOffset'] = startOffset;
final response = await http.post(
Uri.parse(url),
headers: _headers,
- body: jsonEncode({
- 'deviceInfo': {
- 'clientName': 'Absorb',
- 'clientVersion': appVersion,
- 'deviceId': deviceId,
- 'deviceName': '${deviceManufacturer.isNotEmpty ? "$deviceManufacturer " : ""}$deviceModel'.trim(),
- 'manufacturer': deviceManufacturer,
- 'model': deviceModel,
- },
- 'forceDirectPlay': true,
- 'forceTranscode': false,
- 'mediaPlayer': 'unknown',
- 'supportedMimeTypes': [
- 'audio/flac',
- 'audio/mpeg',
- 'audio/mp4',
- 'audio/ogg',
- 'audio/aac',
- ],
- }),
+ body: jsonEncode(body),
).timeout(const Duration(seconds: 20));
debugPrint('[ABS] Play session response: ${response.statusCode}');
diff --git a/lib/services/audio_player_service.dart b/lib/services/audio_player_service.dart
index d853b593..3ec75e4c 100644
--- a/lib/services/audio_player_service.dart
+++ b/lib/services/audio_player_service.dart
@@ -178,6 +178,22 @@ class PlayerSettings {
static Future<bool> getCollapseSeries() => _get('collapseSeries', false);
static Future<void> setCollapseSeries(bool value) => _set('collapseSeries', value, notify: true);
+ // ── Streaming cache ──
+
+ /// 0 = disabled, > 0 = cache size in MB (LRU eviction)
+ static Future<int> getStreamingCacheSizeMb() => _get('streamingCacheSizeMb', 0);
+ static Future<void> setStreamingCacheSizeMb(int value) async {
+ debugPrint('[Settings] Streaming cache set to: $value MB');
+ await _set('streamingCacheSizeMb', value);
+ // Reconfigure the native cache immediately
+ try {
+ await AudioPlayer.configureStreamingCache(value);
+ debugPrint('[Settings] Streaming cache configured on native side');
+ } catch (e) {
+ debugPrint('[Settings] Streaming cache configure failed: $e');
+ }
+ }
+
// ── Library sort/filter persistence ──
static Future<String> getLibrarySort() => _get('librarySort', 'recentlyAdded');
@@ -272,6 +288,12 @@ class PlayerSettings {
class AudioPlayerHandler extends BaseAudioHandler with SeekHandler {
final AudioPlayer _player = AudioPlayer(
handleInterruptions: false,
+ audioLoadConfiguration: const AudioLoadConfiguration(
+ androidLoadControl: AndroidLoadControl(
+ bufferForPlaybackDuration: Duration(milliseconds: 500),
+ bufferForPlaybackAfterRebufferDuration: Duration(milliseconds: 2000),
+ ),
+ ),
);
AudioPlayerService? _service; // back-reference for auto-rewind
@@ -1090,6 +1112,17 @@ class AudioPlayerService extends ChangeNotifier {
// Bind service so handler routes play/pause through service (for auto-rewind)
_handler!.bindService(_instance);
debugPrint('[Player] AudioService initialized');
+ // Configure streaming cache if enabled
+ final cacheSizeMb = await PlayerSettings.getStreamingCacheSizeMb();
+ debugPrint('[Player] Streaming cache setting: $cacheSizeMb MB');
+ if (cacheSizeMb > 0) {
+ try {
+ await AudioPlayer.configureStreamingCache(cacheSizeMb);
+ debugPrint('[Player] Streaming cache configured: $cacheSizeMb MB');
+ } catch (e) {
+ debugPrint('[Player] Streaming cache init failed: $e');
+ }
+ }
// Load notification chapter progress setting and watch for changes
_instance._notifChapterMode = await PlayerSettings.getNotificationChapterProgress();
PlayerSettings.settingsChanged.addListener(_instance._onSettingsChanged);
@@ -1474,13 +1507,14 @@ class AudioPlayerService extends ChangeNotifier {
}
try {
+ _currentTrackIndex = 0;
+
// Build multi-file track offsets for absolute position tracking
if (audioTracks != null) {
_buildTrackOffsets(audioTracks);
} else {
_trackStartOffsets = [0.0]; // single file fallback
}
- _currentTrackIndex = 0;
AudioSource source;
if (localPaths.length == 1) {
@@ -1546,7 +1580,7 @@ class AudioPlayerService extends ChangeNotifier {
}
_playbackSessionId = sessionData['id'] as String?;
- final audioTracks = sessionData['audioTracks'] as List<dynamic>?;
+ var audioTracks = sessionData['audioTracks'] as List<dynamic>?;
if (audioTracks == null || audioTracks.isEmpty) {
_clearState();
return 'No audio files found - this item may be missing on the server';
@@ -1563,6 +1597,7 @@ class AudioPlayerService extends ChangeNotifier {
}
}
+
// Update totalDuration from session if it was unknown (e.g. podcast episodes
// where the embedded recentEpisode didn't include a duration field)
if (totalDuration <= 0) {
@@ -1588,12 +1623,11 @@ class AudioPlayerService extends ChangeNotifier {
}
try {
- // Build multi-file track offsets for absolute position tracking
- _buildTrackOffsets(audioTracks);
_currentTrackIndex = 0;
-
final audioHeaders = api.mediaHeaders;
+ // Build audio source — one source per track file
+ _buildTrackOffsets(audioTracks);
AudioSource source;
if (audioTracks.length == 1) {
final track = audioTracks.first as Map<String, dynamic>;
diff --git a/packages/just_audio/android/build.gradle b/packages/just_audio/android/build.gradle
index ac46ef64..53b16d7d 100644
--- a/packages/just_audio/android/build.gradle
+++ b/packages/just_audio/android/build.gradle
@@ -43,8 +43,8 @@ android {
}
compileOptions {
- sourceCompatibility 1.8
- targetCompatibility 1.8
+ sourceCompatibility JavaVersion.VERSION_11
+ targetCompatibility JavaVersion.VERSION_11
}
dependencies {
diff --git a/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/AudioPlayer.java b/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/AudioPlayer.java
index 15a07bff..1572de6d 100644
--- a/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/AudioPlayer.java
+++ b/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/AudioPlayer.java
@@ -50,6 +50,12 @@ import androidx.media3.exoplayer.trackselection.TrackSelectionArray;
import androidx.media3.datasource.DataSource;
import androidx.media3.datasource.DefaultDataSource;
import androidx.media3.datasource.DefaultHttpDataSource;
+import androidx.media3.datasource.cache.Cache;
+import androidx.media3.datasource.cache.CacheDataSink;
+import androidx.media3.datasource.cache.CacheDataSource;
+import androidx.media3.datasource.cache.LeastRecentlyUsedCacheEvictor;
+import androidx.media3.datasource.cache.SimpleCache;
+import androidx.media3.database.StandaloneDatabaseProvider;
import androidx.media3.common.MimeTypes;
import androidx.media3.common.util.Util;
import io.flutter.Log;
@@ -60,6 +66,7 @@ import io.flutter.plugin.common.MethodCall;
import io.flutter.plugin.common.MethodChannel;
import io.flutter.plugin.common.MethodChannel.MethodCallHandler;
import io.flutter.plugin.common.MethodChannel.Result;
+import java.io.File;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
@@ -75,6 +82,51 @@ public class AudioPlayer implements MethodCallHandler, Player.Listener, Metadata
private static Random random = new Random();
+ // Streaming cache — shared across all player instances
+ private static SimpleCache sCache;
+ private static File sCacheDir;
+
+ @androidx.annotation.OptIn(markerClass = androidx.media3.common.util.UnstableApi.class)
+ static synchronized void configureCache(Context context, long maxBytes) {
+ if (maxBytes <= 0) {
+ releaseCache();
+ return;
+ }
+ File baseDir = context.getExternalCacheDir();
+ if (baseDir == null || !baseDir.exists() || !baseDir.canWrite()) {
+ baseDir = context.getCacheDir();
+ }
+ File cacheDir = new File(baseDir, "streaming_cache");
+ // Already initialized at this location — skip
+ if (sCache != null && cacheDir.equals(sCacheDir)) return;
+ releaseCache();
+ sCacheDir = cacheDir;
+ sCache = new SimpleCache(
+ cacheDir,
+ new LeastRecentlyUsedCacheEvictor(maxBytes),
+ new StandaloneDatabaseProvider(context));
+ Log.d(TAG, "Streaming cache enabled: " + (maxBytes / 1024 / 1024) + " MB at " + cacheDir);
+ }
+
+ @androidx.annotation.OptIn(markerClass = androidx.media3.common.util.UnstableApi.class)
+ static synchronized void releaseCache() {
+ if (sCache != null) {
+ try { sCache.release(); } catch (Exception e) { /* ignore */ }
+ sCache = null;
+ sCacheDir = null;
+ }
+ }
+
+ @androidx.annotation.OptIn(markerClass = androidx.media3.common.util.UnstableApi.class)
+ static synchronized void clearCache() {
+ if (sCache != null) {
+ for (String key : new java.util.HashSet<>(sCache.getKeys())) {
+ sCache.removeResource(key);
+ }
+ Log.d(TAG, "Streaming cache cleared");
+ }
+ }
+
private final Context context;
private final MethodChannel methodChannel;
private final BetterEventChannel eventChannel;
@@ -726,6 +778,7 @@ public class AudioPlayer implements MethodCallHandler, Player.Listener, Metadata
audioEffectsMap.clear();
}
+ @androidx.annotation.OptIn(markerClass = androidx.media3.common.util.UnstableApi.class)
private DataSource.Factory buildDataSourceFactory(Map<?, ?> headers) {
final Map<String, String> stringHeaders = castToStringMap(headers);
String userAgent = null;
@@ -740,11 +793,26 @@ public class AudioPlayer implements MethodCallHandler, Player.Listener, Metadata
}
DefaultHttpDataSource.Factory httpDataSourceFactory = new DefaultHttpDataSource.Factory()
.setUserAgent(userAgent)
- .setAllowCrossProtocolRedirects(true);
+ .setAllowCrossProtocolRedirects(true)
+ .setConnectTimeoutMs(30000)
+ .setReadTimeoutMs(30000);
if (stringHeaders != null && stringHeaders.size() > 0) {
httpDataSourceFactory.setDefaultRequestProperties(stringHeaders);
}
- return new DefaultDataSource.Factory(context, httpDataSourceFactory);
+ DataSource.Factory baseFactory = new DefaultDataSource.Factory(context, httpDataSourceFactory);
+
+ // Wrap with disk cache if enabled
+ if (sCache != null) {
+ return new CacheDataSource.Factory()
+ .setCache(sCache)
+ .setUpstreamDataSourceFactory(baseFactory)
+ .setCacheWriteDataSinkFactory(
+ new CacheDataSink.Factory()
+ .setCache(sCache)
+ .setFragmentSize(CacheDataSink.DEFAULT_FRAGMENT_SIZE))
+ .setFlags(CacheDataSource.FLAG_IGNORE_CACHE_ON_ERROR);
+ }
+ return baseFactory;
}
private void load(final MediaSource mediaSource, final long initialPosition, final Integer initialIndex, final Result result) {
@@ -780,6 +848,9 @@ public class AudioPlayer implements MethodCallHandler, Player.Listener, Metadata
// Set identity matrix so audio passes through by default
monoProcessor.putChannelMixingMatrix(
new androidx.media3.common.audio.ChannelMixingMatrix(2, 2, new float[]{1f, 0f, 0f, 1f}));
+ // Upmix mono sources to stereo so Android AudioTrack handles them reliably
+ monoProcessor.putChannelMixingMatrix(
+ new androidx.media3.common.audio.ChannelMixingMatrix(1, 2, new float[]{1f, 1f}));
sMonoProcessor = monoProcessor;
MonoController.register(AudioPlayer::setMonoEnabled);
RenderersFactory renderersFactory = new DefaultRenderersFactory(context) {
@@ -1022,7 +1093,7 @@ public class AudioPlayer implements MethodCallHandler, Player.Listener, Metadata
private static void setMonoEnabled(final boolean enabled) {
if (sMonoProcessor == null) return;
if (enabled) {
- // Mix both input channels equally into both output channels
+ // Mix both stereo input channels equally into both output channels
sMonoProcessor.putChannelMixingMatrix(
new androidx.media3.common.audio.ChannelMixingMatrix(2, 2, new float[]{0.5f, 0.5f, 0.5f, 0.5f}));
} else {
@@ -1030,6 +1101,9 @@ public class AudioPlayer implements MethodCallHandler, Player.Listener, Metadata
sMonoProcessor.putChannelMixingMatrix(
new androidx.media3.common.audio.ChannelMixingMatrix(2, 2, new float[]{1f, 0f, 0f, 1f}));
}
+ // Always keep mono source upmix matrix regardless of mode
+ sMonoProcessor.putChannelMixingMatrix(
+ new androidx.media3.common.audio.ChannelMixingMatrix(1, 2, new float[]{1f, 1f}));
}
public void setLoopMode(final int mode) {
diff --git a/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/MainMethodCallHandler.java b/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/MainMethodCallHandler.java
index 916423e9..cc4453fe 100644
--- a/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/MainMethodCallHandler.java
+++ b/packages/just_audio/android/src/main/java/com/ryanheise/just_audio/MainMethodCallHandler.java
@@ -48,6 +48,16 @@ public class MainMethodCallHandler implements MethodCallHandler {
result.success(null);
break;
}
+ case "configureStreamingCache": {
+ Integer sizeMb = call.argument("sizeMb");
+ if (sizeMb != null && sizeMb > 0) {
+ AudioPlayer.configureCache(applicationContext, (long) sizeMb * 1024 * 1024);
+ } else {
+ AudioPlayer.releaseCache();
+ }
+ result.success(null);
+ break;
+ }
case "disposePlayer": {
String id = call.argument("id");
AudioPlayer player = players.get(id);
@@ -63,6 +73,11 @@ public class MainMethodCallHandler implements MethodCallHandler {
result.success(new HashMap<String, Object>());
break;
}
+ case "clearStreamingCache": {
+ AudioPlayer.clearCache();
+ result.success(null);
+ break;
+ }
default:
result.notImplemented();
break;
diff --git a/packages/just_audio/lib/just_audio.dart b/packages/just_audio/lib/just_audio.dart
index 84688a2b..f4c454ea 100644
--- a/packages/just_audio/lib/just_audio.dart
+++ b/packages/just_audio/lib/just_audio.dart
@@ -55,6 +55,20 @@ JustAudioPlatform get _pluginPlatform {
/// You must call [dispose] to release the resources used by this player,
/// including any temporary files created to cache assets.
class AudioPlayer {
+ static const MethodChannel _mainChannel =
+ MethodChannel('com.ryanheise.just_audio.methods');
+
+ /// Configure the Android streaming disk cache.
+ /// [sizeMb] = 0 disables the cache. Values > 0 enable LRU caching.
+ static Future<void> configureStreamingCache(int sizeMb) async {
+ await _mainChannel.invokeMethod('configureStreamingCache', {'sizeMb': sizeMb});
+ }
+
+ /// Clear all cached streaming data without disabling the cache.
+ static Future<void> clearStreamingCache() async {
+ await _mainChannel.invokeMethod('clearStreamingCache');
+ }
+
/// The user agent to set on all HTTP requests.
final String? _userAgent;
diff --git a/pubspec.yaml b/pubspec.yaml
index 66e151db..a1ca594d 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,7 +1,7 @@
name: absorb
description: A Material 3 Audiobookshelf client.
publish_to: 'none'
-version: 1.8.8+39
+version: 1.8.9+40
environment:
sdk: '>=3.1.0 <4.0.0'