mp4-rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b330d2181372489c047835f18286ab29f5ec410f3e2af0a8c4ef821cd0aaac39
+  data.tar.gz: 419e94a9e760e037757f13de0e95f40dc3893b3746dfe8e12d5b5700444221be
+SHA512:
+  metadata.gz: e342aceff2bd0cd5fd0dc371ec00059c087f01ee92daf45c6abc589e2fd8f9fa97455f39115bd0ece670ef7c1596fc9246fa9fdbb032caa6b1400d894307ce59
+  data.tar.gz: 57e61066f0372834d3fe92c1c356ba4422306ebad64927c69d7402097f249b02a9e3091671ffac43fb6a0df1d0c9df7fee06d0ab1fa6b45f286a9c8a9171c206

data/Gemfile

@@ -0,0 +1,24 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mp4-rb.gemspec
+gemspec
+
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+
+gem 'colorize', '~> 0.8.1'
+gem 'pry'
+gem 'bindata', '~> 2.4', '>= 2.4.14'
+gem 'axlsx', '~> 2.0.1'
+gem 'virtus'
+gem 'sqlite3', '1.6.0'
+gem 'ruby-progressbar', '~> 1.11'
+gem 'sinatra'
+gem 'webrick'
+gem 'nokogiri'
+gem 'aws-sdk-s3', '~> 1.100', require: false
+
+group :development, :test do
+  gem 'rubocop', '~> 1.60', require: false
+end

data/Gemfile.lock

@@ -0,0 +1,149 @@
+PATH
+  remote: .
+  specs:
+    mp4-rb (0.1.0)
+      axlsx (~> 2.0.1)
+      bindata (~> 2.4)
+      nokogiri (~> 1.15)
+      sqlite3 (~> 1.6.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    aws-eventstream (1.4.0)
+    aws-partitions (1.1267.0)
+    aws-sdk-core (3.253.0)
+      aws-eventstream (~> 1, >= 1.3.0)
+      aws-partitions (~> 1, >= 1.992.0)
+      aws-sigv4 (~> 1.9)
+      base64
+      bigdecimal
+      jmespath (~> 1, >= 1.6.1)
+      logger
+    aws-sdk-kms (1.129.0)
+      aws-sdk-core (~> 3, >= 3.248.0)
+      aws-sigv4 (~> 1.5)
+    aws-sdk-s3 (1.226.0)
+      aws-sdk-core (~> 3, >= 3.248.0)
+      aws-sdk-kms (~> 1)
+      aws-sigv4 (~> 1.5)
+    aws-sigv4 (1.12.1)
+      aws-eventstream (~> 1, >= 1.0.2)
+    axiom-types (0.1.1)
+      descendants_tracker (~> 0.0.4)
+      ice_nine (~> 0.11.0)
+      thread_safe (~> 0.3, >= 0.3.1)
+    axlsx (2.0.1)
+      htmlentities (~> 4.3.1)
+      nokogiri (>= 1.4.1)
+      rubyzip (~> 1.0.0)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    bindata (2.4.14)
+    coderay (1.1.3)
+    coercible (1.0.0)
+      descendants_tracker (~> 0.0.1)
+    colorize (0.8.1)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    diff-lcs (1.5.0)
+    htmlentities (4.3.4)
+    ice_nine (0.11.2)
+    jmespath (1.6.2)
+    json (2.20.0)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    method_source (1.0.0)
+    mini_portile2 (2.8.9)
+    mustermann (3.0.0)
+      ruby2_keywords (~> 0.0.1)
+    nokogiri (1.19.1-arm64-darwin)
+      racc (~> 1.4)
+    parallel (2.1.0)
+    parser (3.3.11.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    racc (1.6.2)
+    rack (2.2.6.4)
+    rack-protection (3.0.6)
+      rack
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.12.0)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.1)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    rubocop (1.88.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.11.0)
+    ruby2_keywords (0.0.5)
+    rubyzip (1.0.0)
+    sinatra (3.0.6)
+      mustermann (~> 3.0)
+      rack (~> 2.2, >= 2.2.4)
+      rack-protection (= 3.0.6)
+      tilt (~> 2.0)
+    sqlite3 (1.6.0)
+      mini_portile2 (~> 2.8.0)
+    thread_safe (0.3.6)
+    tilt (2.1.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    virtus (2.0.0)
+      axiom-types (~> 0.1)
+      coercible (~> 1.0)
+      descendants_tracker (~> 0.0, >= 0.0.3)
+    webrick (1.9.2)
+
+PLATFORMS
+  arm64-darwin-21
+  arm64-darwin-22
+
+DEPENDENCIES
+  aws-sdk-s3 (~> 1.100)
+  axlsx (~> 2.0.1)
+  bindata (~> 2.4, >= 2.4.14)
+  colorize (~> 0.8.1)
+  mp4-rb!
+  nokogiri
+  pry
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.60)
+  ruby-progressbar (~> 1.11)
+  sinatra
+  sqlite3 (= 1.6.0)
+  virtus
+  webrick
+
+BUNDLED WITH
+   2.4.6

data/README.md

@@ -0,0 +1,195 @@
+# mp4-rb
+
+> **Ruby MP4 parser + fMP4 segmenter + on-the-fly HLS/DASH origin server.**
+> A learning project — not production software.
+
+This project originally started as a personal learning exercise and proof of
+concept to better understand the MP4 container format, including its internal
+structure, parsing, and segmentation.
+
+Over time, it evolved into an end-to-end prototype that demonstrates the
+complete media delivery pipeline: parsing MP4 files, generating fragmented
+MP4 (fMP4) segments, and delivering adaptive **HLS** and **DASH** streams.
+
+While this implementation is far from production-ready and doesn't reflect
+the architecture of my current streaming server, it showcases the core
+concepts behind MP4 parsing, segment generation, and adaptive streaming.
+It represents an important milestone in my journey toward building a fully
+featured on-the-fly streaming solution.
+
+## ⚠️ Disclaimer
+
+This project was built **for fun and for learning purposes**. It is not
+maintained as a product, has known rough edges, and should not be used in
+production. If you're here to understand *how* MP4 containers work under
+the hood — how boxes/atoms nest, how the sample table (`stbl`) drives
+timing, how fragmented MP4 initialization and media segments are laid
+out, or how HLS and DASH manifests reference those segments — this
+repository is a good hands-on reference. You can read the code, run the
+demo, break things, and see what happens.
+
+If that sounds useful to you, welcome. If you need a battle-tested
+packager, use [Shaka Packager](https://github.com/shaka-project/shaka-packager)
+or [Bento4](https://www.bento4.com/) instead.
+
+---
+
+## What you can learn from this repo
+
+- **How MP4 is parsed.** Every atom is a `BinData::Record` under
+  [`lib/mp4/binary/`](lib/mp4/binary/) — `ftyp`, `mvhd`, `tkhd`, `stsd`,
+  `stts`, `stsc`, `stsz`, `stco`, `co64`, `ctts`, `elst`, `saio`,
+  `saiz`, `senc`, etc. No hand-rolled `unpack`.
+- **How the sample table drives time.** [`lib/mp4/metadata/memoize/`](lib/mp4/metadata/memoize/)
+  walks the parsed tree and flattens it into a per-sample cache:
+  chunk offset, sample size, decode delta, composition offset,
+  keyframe flag, and PTS in milliseconds.
+- **How fMP4 segments are cut.** [`lib/mp4/nolan/`](lib/mp4/nolan/)
+  divides each track into segments at video keyframes, and
+  [`lib/m4s/`](lib/m4s/) emits the `styp` + `moof` + `mdat` bytes for
+  each media segment plus the `moov` init segment.
+- **How HLS + DASH reference the same segments.**
+  [`lib/m4s/dash/manifest.rb`](lib/m4s/dash/manifest.rb) writes the MPD
+  XML with Nokogiri; [`lib/m4s/m3u8/`](lib/m4s/m3u8/) writes the
+  master + media playlists. Both point at the exact same `.m4s` bytes
+  (CMAF-style shared init) — the server just relabels the URL suffix.
+- **How to serve any of the above on the fly.**
+  [`lib/mp4/server/api.rb`](lib/mp4/server/api.rb) is a Sinatra origin
+  that parses on the first request, memoises the result in an LRU cache,
+  and serves subsequent segment requests in milliseconds. It reads
+  sources from a local directory or from S3-compatible object storage
+  (MinIO in the demo) using `GetObject` byte-range reads.
+
+---
+
+## The `just demo` — one-command reviewer setup
+
+The fastest way to see the whole pipeline working end-to-end is:
+
+```bash
+just demo
+# open http://127.0.0.1:4567/demo
+```
+
+That single command runs `docker compose up --build` on a four-service
+stack. You need **only Docker** installed — no Ruby, no ffmpeg, no
+bundle install.
+
+### What happens when you run `just demo`
+
+1. **Encoder container** synthesises `examples/adaptive_demo.mp4` — a
+   20-minute video generated from `ffmpeg -f lavfi -i testsrc2` +
+   `-f lavfi -i sine` with a `drawtext` HH:MM:SS clock overlay. Four
+   video renditions (1080p / 720p / 480p / 360p) + AAC-LC audio,
+   GOP=48. No external MP4 required. (If you already have the file, this
+   step is skipped.)
+2. **MinIO container** boots an S3-compatible object store on `:9000`
+   (console on `:9001`).
+3. **MinIO-init container** waits for MinIO to become healthy, creates
+   the `videos` bucket, and uploads the fixture with `mc cp`.
+4. **Server container** waits for the encoder AND the S3 upload to
+   complete, then boots the Sinatra origin. Before it accepts a
+   single request, it **pre-warms both caches** (local + S3) by
+   running the full parse → memoise → segmentise pipeline. This
+   takes roughly a minute, and is why the first user hit on
+   `manifest.mpd` is ~200 ms instead of 30 seconds.
+5. Open **http://127.0.0.1:4567/demo** and you get a page with
+   **four shaka-player instances** side-by-side:
+
+   | Card             | Endpoint                                          |
+   | ---------------- | ------------------------------------------------- |
+   | HLS · local      | `/local/adaptive_demo.mp4/master.m3u8`            |
+   | DASH · local     | `/local/adaptive_demo.mp4/manifest.mpd`           |
+   | HLS · S3 (MinIO) | `/s3/videos/adaptive_demo.mp4/master.m3u8`        |
+   | DASH · S3 (MinIO)| `/s3/videos/adaptive_demo.mp4/manifest.mpd`       |
+
+   Each card has a quality picker (1080p → 360p), an ABR toggle,
+   and a live stats overlay (currentTime, buffered, active variant,
+   estimated bandwidth, dropped frames). All four play the same
+   segments concurrently.
+
+Total time from `git clone` to first frame on screen: **~11 minutes**
+on a fresh clone (dominated by the encoder synthesising the 20-minute
+fixture). On subsequent runs, the encoder skips its work and boot
+time drops to under a minute.
+
+### Tearing it down
+
+```bash
+docker compose down                   # stop containers, keep fixture
+docker compose down -v                # also drop MinIO volume
+rm -f examples/adaptive_demo.mp4      # also drop the encoded fixture
+```
+
+---
+
+## Running things without Docker
+
+If you have Ruby 3.x + Bundler + ffmpeg locally, you can also run each
+piece by hand:
+
+```bash
+just install                              # bundle install
+just spec                                 # run the RSpec suite
+just fixture                              # encode examples/adaptive_demo.mp4
+just segments examples/foo.mp4            # emit fMP4 + DASH + HLS to out/fmp4/
+just remux examples/foo.mp4               # regenerate a full MP4 from cache
+just xlsx examples/foo.mp4                # per-sample analysis workbook
+just server                               # boot Sinatra on :4567
+just console                              # IRB with lib/mp4 loaded
+```
+
+---
+
+## Repository layout at a glance
+
+```
+lib/mp4/binary/       — BinData readers, one file per atom
+lib/mp4/layout/       — writers for full MP4 remux
+lib/mp4/metadata/     — parsed tree → per-sample cache
+lib/mp4/nolan/        — keyframe-aligned segmentation
+lib/mp4/cache/        — memory + SQLite cache backends
+lib/mp4/source/       — local, HTTP, S3 source adapters
+lib/mp4/server/       — Sinatra origin + LRU source cache
+lib/m4s/binary/       — BinData readers for fMP4 boxes
+lib/m4s/layout/       — init + media segment writers
+lib/m4s/dash/         — MPD XML generation
+lib/m4s/m3u8/         — master + media playlist generation
+```
+
+---
+
+## Development
+
+```bash
+just install
+just spec
+just lint
+```
+
+`bin/console` (`just console`) drops you into an IRB with `MP4` loaded.
+It's the most useful way to poke at a real file:
+
+```ruby
+mp4 = MP4.new(path: './examples/some.mp4')
+mp4.cache.tracks
+mp4.cache.chunks(1).first
+mp4.build_dash_manifest_xml(init_segment_path: nil, segment_path: nil)
+```
+
+---
+
+## Not in scope
+
+- DRM (Widevine / PlayReady / FairPlay) — parsing of `senc`/`saio`/`saiz`
+  is implemented, but nothing is encrypted end-to-end.
+- Live streaming — this is a VOD-only prototype.
+- Production hardening — no authentication, no rate limiting, no CDN
+  fronting. Do not expose this to the public internet.
+
+---
+
+## License
+
+MIT-ish personal project. Use whatever you learn here freely; blame
+nobody but yourself if you ship it to production.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/build_mp4_xlsx.rb

@@ -0,0 +1,35 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# Emit an XLSX analysis workbook (one sheet per track, per-sample rows) for the
+# given input MP4.
+#
+# Usage:
+#   bin/build_mp4_xlsx.rb <input.mp4> [output.xlsx]
+#   MP4_INPUT=path.mp4 MP4_OUTPUT=out.xlsx bin/build_mp4_xlsx.rb
+
+require 'fileutils'
+require_relative '../lib/mp4'
+
+input = ARGV[0] || ENV['MP4_INPUT']
+if input.nil? || input.empty?
+  MP4.logger.error 'usage: bin/build_mp4_xlsx.rb <input.mp4> [output.xlsx]'
+  exit 1
+end
+unless File.file?(input)
+  MP4.logger.error "input not found: #{input}"
+  exit 1
+end
+
+output = ARGV[1]
+output = ENV['MP4_OUTPUT'] if output.nil? || output.empty?
+if output.nil? || output.empty?
+  base   = File.basename(input, File.extname(input))
+  output = "out/xlsx/#{base}.xlsx"
+end
+FileUtils.mkdir_p(File.dirname(output))
+
+MP4.logger.info "Input:  #{input}"
+MP4.logger.info "Output: #{output}"
+
+MP4.new(path: input).build_xslx(output)

data/bin/divide_mp4_to_segments.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# Emit a full fMP4 DASH/HLS package for the given input MP4:
+#   init-N.mp4                  (one per track)
+#   chunk-{track-1}-NNNNN.m4s   (one per segment per track)
+#   manifest.mpd                (DASH)
+#   general_playlist.m3u8       (HLS master)
+#   playlist-{track-1}.m3u8     (HLS media per track)
+#
+# Usage:
+#   bin/divide_mp4_to_segments.rb <input.mp4> [output_dir]
+#   MP4_INPUT=path.mp4 MP4_OUTPUT=out/ bin/divide_mp4_to_segments.rb
+#
+# ENV:
+#   MP4_INPUT     — input MP4 path (overridden by ARGV[0])
+#   MP4_OUTPUT    — output directory (overridden by ARGV[1])
+#   XLSX          — if set, also write an XLSX analysis to out/xlsx/<name>.xlsx
+
+require 'fileutils'
+require_relative '../lib/mp4'
+
+input = ARGV[0] || ENV['MP4_INPUT']
+if input.nil? || input.empty?
+  MP4.logger.error 'usage: bin/divide_mp4_to_segments.rb <input.mp4> [output_dir]'
+  exit 1
+end
+unless File.file?(input)
+  MP4.logger.error "input not found: #{input}"
+  exit 1
+end
+
+output = ARGV[1]
+output = ENV['MP4_OUTPUT'] if output.nil? || output.empty?
+if output.nil? || output.empty?
+  base   = File.basename(input, File.extname(input))
+  output = "out/fmp4/#{base}/"
+end
+FileUtils.mkdir_p(output)
+
+MP4.logger.info "Input:  #{input}"
+MP4.logger.info "Output: #{output}"
+
+mp4 = MP4.new(path: input)
+mp4.save_fmp4_segments_to(output)
+
+if ENV['XLSX']
+  xlsx_path = "out/xlsx/#{File.basename(input, File.extname(input))}.xlsx"
+  FileUtils.mkdir_p(File.dirname(xlsx_path))
+  mp4.build_xslx(xlsx_path)
+  MP4.logger.info "XLSX:   #{xlsx_path}"
+end

data/lib/m4s/binary/ftyp.rb

@@ -0,0 +1,11 @@
+module M4S
+  module Binary
+    class Ftyp < BinData::Record
+      endian :big
+
+      string :major_brand, length: 4
+      uint32 :minor_version
+      rest :compatible_brands
+    end
+  end
+end

data/lib/m4s/binary/mfhd.rb

@@ -0,0 +1,18 @@
+# mfhd = MP4::Binary::Mfhd.new(
+#   size: 16,
+#   version: 0,
+#   flags: 0,
+#   sequence_number: 1
+# )
+#
+module M4S
+  module Binary
+    class Mfhd < BinData::Record
+      endian :big
+
+      uint8  :version
+      bit24  :flags
+      uint32 :sequence_number
+    end
+  end
+end

data/lib/m4s/binary/mvhd.rb

@@ -0,0 +1,39 @@
+module M4S::Binary
+  class Mvhd < BinData::Record
+    endian :big
+
+    bit1 :version, value: 0
+    array :flags, initial_length: 3, type: :uint8
+
+    uint32 :creation_time
+    uint32 :modification_time
+    uint32 :timescale
+    uint32 :duration
+
+    fixed_point16 :rate
+    fixed_point8 :volume
+
+    skip length: 2 + 4 + 4
+
+    array :matrix, initial_length: 9, type: :uint32
+
+    skip length: 4 * 6
+
+    uint32 :next_track_id
+  end
+end
+# ISO/IEC 14496-12:2015(E)
+# SEMANTICS:
+# `version` - is an integer that specifies the version of this box (0 or 1 in this specification) creation_time is an integer that declares the creation time of the presentation (in seconds
+# `since` - midnight, Jan. 1, 1904, in UTC time)
+# `modification_time` - is an integer that declares the most recent time the presentation was
+# `modified` - (in seconds since midnight, Jan. 1, 1904, in UTC time)
+# `timescale` - is an integer that specifies the time‐scale for the entire presentation; this is the
+# `number` - of time units that pass in one second. For example, a time coordinate system that
+# `measures` - time in sixtieths of a second has a time scale of 60.
+# `duration` - is an integer that declares length of the presentation (in the indicated timescale). This
+# `property` - is derived from the presentation’s tracks: the value of this field corresponds to the duration of the longest track in the presentation. If the duration cannot be determined then duration is set to all 1s.
+# `rate` - is a fixed point 16.16 number that indicates the preferred rate to play the presentation; 1.0 (0x00010000) is normal forward playback
+# `volume` - is a fixed point 8.8 number that indicates the preferred playback volume. 1.0 (0x0100) is full volume.
+# `matrix - provides a transformation matrix for the video; (u,v,w) are restricted here to (0,0,1), hex values (0,0,0x40000000).
+# `next_track_ID` - is a non‐zero integer that indicates a value to use for the track ID of the next track to be added to this presentation. Zero is not a valid track ID value. The value of next_track_ID shall be larger than the largest track‐ID in use. If this value is equal to all 1s (32‐bit maxint), and a new media track is to be added, then a search must be made in the file for an unused track identifier.

data/lib/m4s/binary/sidx.rb

@@ -0,0 +1,38 @@
+# sidx = MP4::Binary::Sidx.new(
+#   size: 52,
+#   version: 1,
+#   flags: 0,
+#   reference_id: 1,
+#   timescale: 24000,
+#   earliest_presentation_time: 0,
+#   first_offset: 0,
+#   references: [
+#     { reference_type: 0, size: 3040256, duration: 216216, starts_with_sap: 1, sap_type: 0, sap_delta_time: 0 }
+#   ]
+# )
+
+module M4S
+  module Binary
+    class Sidx < BinData::Record
+      endian :big
+
+      uint8  :version
+      bit24  :flags
+      uint32 :reference_id
+      uint32 :timescale
+      uint64 :earliest_presentation_time
+      uint64 :first_offset
+      uint16 :reserved, value: 0
+      uint16 :reference_count
+
+      array :references, initial_length: :reference_count do
+        bit1   :reference_type
+        bit31  :referenced_size
+        uint32 :subsegment_duration
+        bit1   :starts_with_sap
+        bit3   :sap_type
+        bit28  :sap_delta_time
+      end
+    end
+  end
+end

data/lib/m4s/binary/styp.rb

@@ -0,0 +1,17 @@
+# styp = M4S::Binary::Styp.new(
+#   major_brand: "msdh",
+#   minor_version: 0,
+#   compatible_brands: ["msdh", "msix"]
+# )
+
+module M4S
+  module Binary
+    class Styp < BinData::Record
+      endian :big
+
+      string :major_brand, length: 4
+      uint32 :minor_version
+      array :compatible_brands, type: :string
+    end
+  end
+end

data/lib/m4s/binary/tfdt.rb

@@ -0,0 +1,25 @@
+# tfdt = M4S::Binary::Tfdt.new(
+#   version: M4S::Binary::Tfdt::VERSION_1,
+#   flags: 0,
+#   base_media_decode_time: 1234567890
+# )
+
+# Track Fragment Base Media Decode Time Box
+module M4S
+  module Binary
+    class Tfdt < BinData::Record
+      endian :big
+
+      VERSION_0 = 0
+      VERSION_1 = 1
+
+      uint8  :version
+      bit24  :flags
+
+      choice :base_media_decode_time, selection: :version do
+        uint32 VERSION_0
+        uint64 VERSION_1
+      end
+    end
+  end
+end

data/lib/m4s/binary/tfhd.rb

@@ -0,0 +1,38 @@
+# tfhd = M4S::Binary::Tfhd.new(
+#   version: 0,
+#   flags: M4S::Binary::Tfhd::FLAGS.values.reduce(:|), # Пример: все опциональные поля присутствуют
+#   track_id: 1,
+#   base_data_offset: 0, # только если флаг 0x000001 установлен
+#   sample_description_index: 1, # только если флаг 0x000002 установлен
+#   default_sample_duration: 1001, # только если флаг 0x000008 установлен
+#   default_sample_size: 907, # только если флаг 0x000010 установлен
+#   default_sample_flags: 0 # только если флаг 0x000020 установлен
+# )
+
+# Track Fragment Header Box
+module M4S
+  module Binary
+    class Tfhd < BinData::Record
+      endian :big
+
+      FLAGS = {
+        base_data_offset: 0x000001,
+        sample_description_index: 0x000002,
+        default_sample_duration: 0x000008,
+        default_sample_size: 0x000010,
+        default_sample_flags: 0x000020,
+      }.freeze
+
+      uint8  :version
+      bit24  :flags
+      uint32 :track_id
+
+      # Опциональные поля, которые зависят от флагов
+      uint64 :base_data_offset, onlyif: -> { flags & FLAGS[:base_data_offset] != 0 }
+      uint32 :sample_description_index, onlyif: -> { flags & FLAGS[:sample_description_index] != 0 }
+      uint32 :default_sample_duration, onlyif: -> { flags & FLAGS[:default_sample_duration] != 0 }
+      uint32 :default_sample_size, onlyif: -> { flags & FLAGS[:default_sample_size] != 0 }
+      uint32 :default_sample_flags, onlyif: -> { flags & FLAGS[:default_sample_flags] != 0 }
+    end
+  end
+end