moonmedia

• mp4 — ISO base media files and fragments, read and written back byte for byte, with the sample tables walked into frames.
• m3u8 — HLS playlists: master and media, every tag of RFC 8216, and the low-latency tags of RFC 8216bis.
• ts — MPEG-2 transport streams: packets, the programme tables, the elementary streams inside them and the clock that times them.
• rtmp — the publish side: handshake, chunk stream, commands, and the state machine a publisher drives.
• mpd — DASH manifests, read into a model and written back as XML.
• moonmedia — the packager that ties them together: an MP4 in, key-frame segments and the playlists that name them out.

#Install

moon add moonbitstack/moonmedia

#Cutting a movie into an HLS package

///|
test {
  // `movie` is a file's bytes, from wherever the caller got them.
  let file = @mp4.Mp4::parse(movie)
  let packager = @moonmedia.Packager::new(file, target_duration=6.0)
  // What a player needs before it can decode anything.
  let init = packager.init_segment()
  // Each segment is a movie fragment: a `moof` and the `mdat` it points at.
  for segment in packager.segments() {
    println(segment.data.length().to_string() + " bytes, " +
      segment.duration.to_string() + " s")
  }
  // The playlist that names them, ready to be served as text.
  println(packager.media_playlist().encode())
}

#Reading and writing playlists

///|
test {
  let text =
    #|#EXTM3U
    #|#EXT-X-VERSION:7
    #|#EXT-X-TARGETDURATION:6
    #|#EXT-X-MAP:URI="init.mp4"
    #|#EXTINF:6,
    #|segment0.m4s
    #|#EXT-X-ENDLIST
  match @m3u8.Playlist::parse(text) {
    MediaPlaylist(media) => {
      println(media.segments.length().to_string() + " segments")
      // The key and the map in force for a segment are resolved for you: a tag
      // applies until it is replaced, and the segment carries the result.
      for segment in media.segments {
        println(segment.uri + " " + segment.duration.to_string())
      }
    }
    MasterPlaylist(master) =>
      for variant in master.variants {
        println(variant.uri + " at " + variant.bandwidth.unwrap().to_string())
      }
  }
}

///|
test {
  let media = @m3u8.MediaPlaylist::new(6)
  media.version = Some(7)
  media.playlist_type = Some(@m3u8.PlaylistType::Vod)
  media.end_list = true
  let init = @m3u8.InitSection::new("init.mp4")
  for i = 0; i < 4; i = i + 1 {
    let segment = @m3u8.Segment::new("segment" + i.to_string() + ".m4s", 6.0)
    segment.map = Some(init)
    media.segments.push(segment)
  }
  let text = media.encode()
  println(text)
}

#Reading a movie

///|
test {
  let file = @mp4.Mp4::parse(bytes)
  for box in file.boxes {
    println(box.type_ + " " + box.byte_length().to_string())
  }
  // The samples of every track, from the sample table of a plain file or from
  // the fragments of a fragmented one.
  for track in file.tracks() {
    println(track.codec + " " + track.width.to_string() + "x" +
      track.height.to_string() + ", " + track.samples.length().to_string() +
      " frames")
    for sample in track.samples {
      // Where the frame is, how long it plays, and whether a player may start
      // on it.
      println(sample.offset.to_string() + " " + sample.duration.to_string() +
        " " + sample.sync.to_string())
    }
  }
}

#Transport streams

///|
test {
  let packets = @ts.parse(bytes)
  let pat = @ts.Pat::of(@ts.sections(packets, @ts.pat_pid)[0])
  let pmt = @ts.Pmt::of(@ts.sections(packets, pat.programs[0].pid)[0])
  println(
    "programme " + pmt.program.to_string() +
    ", clock on pid " + pmt.pcr_pid.to_string(),
  )
  for stream in pmt.streams {
    println("type " + stream.stream_type.to_string() + " on " + stream.pid.to_string())
  }
  // The frames of one elementary stream, with their timestamps.
  for frame in @ts.pes_packets(packets, pmt.streams[0].pid) {
    println(frame.data.length().to_string() + " bytes at " +
      frame.pts().unwrap().to_string())
  }
}

#Taking a publish

///|
test {
  let session = @rtmp.Session::new()
  // Whatever came off the socket, in the order it came.
  for reply in session.push(bytes) {
    println(reply.length().to_string() + " bytes to send back")
  }
  match session.phase() {
    Publishing => {
      println(session.app() + "/" + session.stream_name())
      for message in session.take_media() {
        println(message.type_.to_string() + " " + message.timestamp.to_string())
      }
    }
    _ => println("still setting up")
  }
}

#DASH manifests

///|
test {
  let manifest = @mpd.Manifest::parse(text)
  println(@mpd.format_duration(manifest.duration.unwrap()))
  for period in manifest.periods {
    for set in period.adaptations {
      for representation in set.representations {
        println(representation.id + " " +
          representation.bandwidth.unwrap().to_string() + " bit/s")
      }
    }
  }
  // Writing it back gives a manifest a player reads the same way.
  println(manifest.encode())
}

#How the packages behave

#The API, package by package

#moonbitstack/moonmedia/mp4

#moonbitstack/moonmedia/m3u8

#moonbitstack/moonmedia/ts

#moonbitstack/moonmedia/rtmp

#moonbitstack/moonmedia/mpd

#moonbitstack/moonmedia

#Examples

moon run src/examples/01-playlists   # build a master and a media playlist, read both back
moon run src/examples/02-boxes       # a fragment written, read, and walked
moon run src/examples/03-package     # an MP4 cut into segments, with the playlists
moon run src/examples/04-transport   # tables and a frame, as transport stream packets
moon run src/examples/05-manifest    # a DASH manifest, printed as XML
moon run src/examples/06-ingest      # a publish session driven from handshake to media

#Licence