glb_stream

A pure-Dart streaming parser for the glTF 2.0 binary container (.glb) format. Reads from any Stream<List<int>> and yields the header, JSON chunk, and binary chunk progressively — without buffering the whole file into memory at once.

When to use this

You're loading a .glb file from an HTTP byte stream, a File opened with openRead(), or any other byte-source where the full asset isn't already in memory.
You want UI feedback (placeholder scene, progress indicator) while the binary chunk streams.
You're targeting Flutter on web, embedded, or constrained-memory devices where holding a multi-hundred-megabyte Uint8List is impractical.

When to use something else

This package is a container parser: it gives you the GLB's JSON chunk (the glTF document) and a Stream over the binary chunk. It does not render anything, and it does not resolve sub-resources (buffers, accessors, images) into renderable structures. Choose based on what you need:

If you want…	Use
Full glTF 2.0 document model with 20+ KHR extensions and lazy sub-resource access	`gltf_loader` (pure Dart; bulk parse with callback-style sub-resource fetch)
Synchronous bulk-load of a `.glb` from a file path (no streaming, dart:io only)	`super_glb`
Rendering a glTF in Flutter via offline-imported scenes	`flutter_scene` with `flutter_scene_importer` build-time conversion
Rendering a glTF in Flutter via Filament FFI	`thermion` with `FilamentAsset`
Container-level streaming parse from `Stream<List<int>>` (this package)	`glb_stream`

The differentiator is the input shape: glb_stream consumes a Stream<List<int>> and yields parsed chunks progressively, suitable for HTTP downloads, file streams, and isolate-bridged byte sources without an intermediate Uint8List of the full asset.

Usage

import 'package:glb_stream/glb_stream.dart';

final byteStream = httpResponse.stream; // or File.openRead(), etc.
final parser = GlbStreamParser();

await for (final event in parser.parse(byteStream)) {
  switch (event) {
    case GlbHeader header:
      // 12-byte header: magic 'glTF', version, total length
      print('glTF version ${header.version}, ${header.length} bytes total');
    case GlbJsonChunk json:
      // The glTF document as a Map<String, dynamic>
      print('Scene count: ${(json.document['scenes'] as List?)?.length}');
    case GlbBinaryChunkData bin:
      // Binary chunk bytes arrive in stream order (may be split across events)
      // bin.offset / bin.length describe the position within the binary chunk
  }
}

Spec compliance

Implements the GLB container format from the Khronos glTF 2.0 specification:

12-byte header (glTF magic, version 2, total length)
JSON chunk (JSON type tag, padded to 4-byte boundary)
Optional BIN chunk (BIN\0 type tag, padded to 4-byte boundary)

The package does NOT parse the glTF JSON document beyond decoding it from UTF-8 — that's the next layer up.

Status

Early-API release. 0.x versions may break before 1.0. Targeted use cases: Flutter automotive 3D viewers, IVI/cabin display content streaming, photogrammetry workflow tooling, crash-test 3D archival workflows.

License

BSD-3-Clause. Compatible with MIT-licensed flutter_scene and Apache-2.0-licensed thermion downstream consumers.