Flutter Soloud Pull Streaming

flutter_soloud pull-buffer streaming

In flutter_soloud, "pull" streaming means the engine owns the data demand: you create an AudioSource with setPullBufferStream(...) declaring the total encoded size, and the engine calls your onMoreDataIsNeeded(offset) callback whenever it wants the next chunk of encoded bytes at a specific byte offset. You fetch the bytes (HTTP Range request, file read, decryptor, custom protocol) and hand them back via addPullBufferDataStream. Decoded audio lives in a fixed-size circular buffer, so memory stays bounded regardless of source size — a 10 GB file can play with a 5 MB buffer. Seeking works: after SoLoud.instance.seek(handle, pos), the engine re-issues onMoreDataIsNeeded at the byte offset for the new position. One pull stream = one playback voice.

Minimal example

import 'package:flutter/foundation.dart';
import 'package:flutter_soloud/flutter_soloud.dart';

Future<void> playHugeFile(
  Uint8List Function(int offset, int length) fetchRange,
  int totalBytes,
) async {
  await SoLoud.instance.init(); // must complete before any other call

  // Declare first: the callback closure must reference the source, and a
  // local can't be referenced inside its own initializer.
  late final AudioSource source;
  source = SoLoud.instance.setPullBufferStream(
    audioSizeBytes: totalBytes, // REQUIRED, non-zero, known upfront
    bufferSizeBytes: 5 * 1024 * 1024, // decoded circular buffer, ~14 s stereo f32
    bufferTriggerPosition: 0.8, // default; ask for more when 20% ahead remains
    format: BufferType.auto, // default; detects MP3, WAV, FLAC, OGG, AAC, AC-3, E-AC-3
    onAudioDuration: (seconds) {/* total duration is now known */},
    onMetadata: (metadata) {/* detected format, sample rate, channels */},
    onMoreDataIsNeeded: (offset) {
      const chunkSize = 64 * 1024;
      final end = (offset + chunkSize).clamp(0, totalBytes);
      if (offset < 0 || offset >= totalBytes) return;
      SoLoud.instance.addPullBufferDataStream(
        source,
        fetchRange(offset, end - offset),
        offset: offset,
      );
    },
  );

  final handle = SoLoud.instance.play(source);

  // Seeking is free: the engine re-requests data at the new offset.
  SoLoud.instance.seek(handle, const Duration(minutes: 2));

  // No end-of-stream call exists: when sequential data reaches
  // audioSizeBytes the engine ends the stream itself.
  // Dispose on teardown: SoLoud.instance.deinit();
}

The API shape

All on SoLoud.instance (lib/src/soloud.dart). Real signatures:

AudioSource setPullBufferStream({
  int bufferSizeBytes = 1024 * 1024 * 10, // 10 MB
  double bufferTriggerPosition = 0.8,
  int sampleRate = 44100,
  Channels channels = Channels.stereo,
  BufferType format = BufferType.auto,
  int audioSizeBytes = 0,        // 0 throws SoLoudCppException(invalidParameter)
  bool autoDispose = false,
  void Function(bool isBuffering, int handle, double time)? onBuffering,
  void Function(AudioMetadata)? onMetadata,
  void Function(double duration)? onAudioDuration,
  void Function(int offset)? onMoreDataIsNeeded,
});

void resetPullBufferStream(AudioSource sound);

PlayerErrors addPullBufferDataStream(
  AudioSource source,
  Uint8List audioChunk, {
  int offset = 0, // byte offset in the ENCODED stream
});

({PlayerErrors error, Duration startTime, Duration endTime})
  getPullBufferTimeRange(AudioSource source);

• setPullBufferStream returns an AudioSource synchronously (unlike loadAsset/loadFile, which are async) and throws SoLoudCppException on error. Play it with the usual synchronous SoLoud.instance.play(source).
• audioSizeBytes is the total size of the encoded source and is mandatory upfront (server Content-Length, file length). It drives duration calculation and end-of-stream detection; for Ogg formats the engine also uses it to request the tail chunk for duration probing.
• bufferTriggerPosition is about how much decoded audio remains ahead of the playhead, not absolute fill level: 0.8 fires the request when the playhead is within the last 20% of the decoded window. Values outside [0.0, 1.0] are clamped.
• sampleRate/channels are ignored when format is BufferType.auto (the common case); they only matter for raw PCM formats (f32le, s8, s16le, s32le).
• addPullBufferDataStream takes a named offset. offset: 0 means "append the next sequential chunk" — always pass the real requested offset from the callback instead. Empty chunks are a no-op returning PlayerErrors.noError.
• getPullBufferTimeRange returns the decoded window currently in the circular buffer as Durations; the playhead normally sits near startTime. Use it to render a buffered-range indicator and to detect "smart" seeks (target inside the window = no refetch needed).
• Divergence from audioplayers/just_audio: there is no setUrl, no player.durationStream, no AudioSource.uri. Duration arrives asynchronously through the onAudioDuration callback (seconds as double), and position is polled with SoLoud.instance.getPosition(handle). There is no Source object per URL — you are the transport.

Pull vs push

flutter_soloud has two streaming APIs; pick by source shape:

• Pull (setPullBufferStream) — the source is seekable/addressable and you know its size: HTTP servers with Range support, local files, encrypted containers. Supports arbitrary seek and bounded memory. This skill.
• Push (setBufferStream + addAudioDataStream + setDataIsEnded) — data arrives sequentially with no random access: live radio, microphone feeds, procedurally generated audio. See the sibling skill flutter-soloud-streaming.

Traps

• MP4 and M4A containers are NOT supported for streaming. While MP4/M4A audio files are supported for whole-file loading (loadFile/loadAsset/loadMem), streaming chunks from MP4/M4A containers is not supported. Use streamable elementary formats (AAC ADTS, AC-3, E-AC-3, OGG, MP3, WAV, or raw PCM).
• Linux requirement for AAC / AC-3 / E-AC-3. On Linux, streaming these formats requires FFmpeg shared libraries (libavcodec and libavformat) installed on the host system (sudo apt install ffmpeg libavcodec-extra, sudo pacman -S ffmpeg, etc.). Core formats (MP3, WAV, FLAC, OGG) work without FFmpeg.
• Web browser limitation for AC-3 / E-AC-3. AC-3 and E-AC-3 streaming is not supported on the Web platform in any browser. Chrome and Firefox lack Dolby licensing, and Safari's WebCodecs engine rejects raw AC-3 elementary stream frames. AC-3 and E-AC-3 streaming is supported only on native platforms (iOS, macOS native, Android, Windows, and Linux with FFmpeg). On Web, feeding AC-3/E-AC-3 stream data returns PlayerErrors.audioFormatNotSupported. For cross-browser web streaming, use AAC (ADTS), Opus, MP3, FLAC, or raw PCM.
• audioSizeBytes of 0 throws. setPullBufferStream calls SoLoudCppException.fromPlayerError(PlayerErrors.invalidParameter) when it is 0. Do a HEAD request / stat the file first. A server that omits Content-Length and Accept-Ranges: bytes is a poor fit for pull.
• Do not invent an end-of-stream call. There is no setDataIsEnded for pull streams (that belongs to the push API). The stream ends automatically once sequential data reaches audioSizeBytes.
• The callback can re-fire for the same offset and fire out of order. Deduplicate in-flight requests (_pendingOffsets.add(offset) pattern) and guard offset < 0 || offset >= audioSizeBytes — the engine may probe the tail for Ogg duration. addPullBufferDataStream accepts out-of-order chunks precisely for this.
• Seek invalidates your dedup state. After an out-of-buffer seek(handle, pos), the engine re-requests offsets you may have already served. Clear your "already fetched" set on such seeks, or the re-requested bytes never arrive and playback stalls silently. Seeks inside the current getPullBufferTimeRange window are free and need no refetch.
• One voice per stream. A pull AudioSource is tied to a single playing instance; create a new stream for a new voice. PlayerErrors.invalidPullBufferState / hashIsNotAPullBufferStream mean you called a pull method on the wrong source or at the wrong time.
• Web: replacing a stream. Disposing the old pull source while the audio thread still processes it can crash/deadlock. The example works around this by leaving the old source in the engine and letting callbacks capture their own currentSource, dropping callbacks whose source is stale (currentSource != _source). Web also requires the server to send CORS headers for Range requests.
• Chunk size is yours to choose. The engine only tells you where, not how much. ~64 KB keeps HTTP overhead reasonable and the trigger firing; chunks larger than the whole file defeat the pull model (everything decodes in the first callback).
• Playhead lives at the buffer's edge. The decoded window slides forward; the playhead stays near startTime, not centered in a large pre-buffered region. Don't design UX around a just_audio-style bufferedPosition far ahead of playback.
• Errors from addPullBufferDataStream throw. It returns PlayerErrors but throws SoLoudCppException on any non-noError result — wrap feeds in try/catch and stop feeding a broken stream.