-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A pure EBML parser
--   
--   Pure decoder for the Extensible Binary Meta Language (EBML) format.
--   
--   Use this library to parse mkv/webm file or split a webm stream
--   segments.
--   
--   Checkout a motivating use-case presented in this blog post:
--   <a>Broadcasting a WebM stream using MSE</a>.
--   
--   Read the haskell-ebml demo app for simple usage: <a>Main.hs</a>.
@package ebml
@version 0.1.1.0


-- | This module is intended to be imported qualified:
--   
--   <pre>
--   import qualified Codec.EBML as EBML
--   </pre>
--   
--   Decode a webm file with:
--   
--   <pre>
--   EBML.decodeWebMFile "path/file.webm"
--   </pre>
--   
--   Split a webm stream segments with:
--   
--   <pre>
--   let streamReader = EBML.newStreamReader
--   buf &lt;- acquire data
--   EBML.feedReader buf streamReader
--   </pre>
--   
--   References:
--   
--   <ul>
--   <li>EBML specification introduction:
--   <a>https://matroska-org.github.io/libebml/specs.html</a></li>
--   <li>Document layout:
--   <a>https://www.matroska.org/technical/diagram.html</a></li>
--   <li>The matroska schema:
--   <a>https://github.com/ietf-wg-cellar/matroska-specification/blob/master/ebml_matroska.xml</a></li>
--   <li>The matroska schema doc:
--   <a>https://www.matroska.org/technical/elements.html</a></li>
--   <li>The webm guidelines:
--   <a>https://www.webmproject.org/docs/container/</a></li>
--   <li>The MSE byte stream format spec:
--   <a>https://w3c.github.io/media-source/index.html#byte-stream-format-specs</a></li>
--   <li>The MSE byte stream format for webm:
--   <a>https://w3c.github.io/mse-byte-stream-format-webm/</a></li>
--   </ul>
module Codec.EBML

-- | Lazy decode a <a>WebMDocument</a>.
decodeWebM :: ByteString -> Either Text WebMDocument

-- | A WebM document.
data WebMDocument
WebMDocument :: Word64 -> [WebMCluster] -> WebMDocument

-- | Base unit for Segment Ticks and Track Ticks, in nanoseconds. A
--   TimestampScale of 1_000_000 means segments' timestamps are expressed
--   in milliseconds;
[$sel:timestampScale:WebMDocument] :: WebMDocument -> Word64

-- | The list of clusters.
[$sel:clusters:WebMDocument] :: WebMDocument -> [WebMCluster]

-- | A WebM cluster, e.g. a media segment.
data WebMCluster
WebMCluster :: Word64 -> [EBMLElement] -> WebMCluster

-- | Absolute timestamp of the cluster.
[$sel:timestamp:WebMCluster] :: WebMCluster -> Word64

-- | The cluster elements.
[$sel:content:WebMCluster] :: WebMCluster -> [EBMLElement]

-- | Lazy decode a <a>EBMLDocument</a>.
decodeEBMLDocument :: [EBMLSchema] -> ByteString -> Either Text EBMLDocument

-- | The webm document schemas.
webmSchemas :: [EBMLSchema]

-- | Create a stream reader with <a>newStreamReader</a>, and decode media
--   segments with <a>feedReader</a>.
data StreamReader

-- | Initialize a stream reader.
newStreamReader :: StreamReader

-- | A valid frame that can be served.
data StreamFrame
StreamFrame :: ByteString -> ByteString -> StreamFrame

-- | The initialization segments, to be provided before the first media
--   segment.
[$sel:initialization:StreamFrame] :: StreamFrame -> ByteString

-- | The begining of the last media segment found in the input buffer.
[$sel:media:StreamFrame] :: StreamFrame -> ByteString

-- | Feed data into a stream reader. Returns either an error, or maybe a
--   new <a>StreamFrame</a> and an updated StreamReader.
feedReader :: ByteString -> StreamReader -> Either Text (Maybe StreamFrame, StreamReader)

-- | EBML document structure, including the Header and Body Root.
newtype EBMLDocument
EBMLDocument :: [EBMLElement] -> EBMLDocument

-- | EBML element.
data EBMLElement
EBMLElement :: EBMLElementHeader -> EBMLValue -> EBMLElement
[$sel:header:EBMLElement] :: EBMLElement -> EBMLElementHeader
[$sel:value:EBMLElement] :: EBMLElement -> EBMLValue

-- | EBML element value.
data EBMLValue
EBMLRoot :: [EBMLElement] -> EBMLValue
EBMLSignedInteger :: Int64 -> EBMLValue
EBMLUnsignedInteger :: Word64 -> EBMLValue
EBMLFloat :: Double -> EBMLValue
EBMLText :: Text -> EBMLValue
EBMLDate :: Text -> EBMLValue
EBMLBinary :: ByteString -> EBMLValue

-- | EBML element header.
data EBMLElementHeader
EBMLElementHeader :: EBMLID -> Maybe Word64 -> EBMLElementHeader
[$sel:eid:EBMLElementHeader] :: EBMLElementHeader -> EBMLID

-- | size is Nothing for unknown-sized element.
[$sel:size:EBMLElementHeader] :: EBMLElementHeader -> Maybe Word64

-- | EBML element id.
newtype EBMLID
EBMLID :: Word32 -> EBMLID

-- | EBML schema definition.
--   
--   Note that this is missing:
--   
--   <ul>
--   <li>min/max occurrence constraint.</li>
--   <li>default value.</li>
--   <li>element path.</li>
--   </ul>
data EBMLSchema
EBMLSchema :: Text -> EBMLID -> (EBMLSchemas -> EBMLElementHeader -> Get EBMLValue) -> EBMLSchema

-- | The element name.
[$sel:name:EBMLSchema] :: EBMLSchema -> Text

-- | The element id.
[$sel:eid:EBMLSchema] :: EBMLSchema -> EBMLID

-- | How to decode the element value.
[$sel:decode:EBMLSchema] :: EBMLSchema -> EBMLSchemas -> EBMLElementHeader -> Get EBMLValue

-- | Decode a raw EBML file.
decodeEBMLFile :: [EBMLSchema] -> FilePath -> IO (Either Text EBMLDocument)

-- | Decode a webm file.
decodeWebMFile :: FilePath -> IO (Either Text WebMDocument)

-- | Pretty-print a <a>EBMLDocument</a>.
prettyEBMLDocument :: [EBMLSchema] -> EBMLDocument -> Text
data EBMLSchemas

-- | Combine a list of schema for decoder.
compileSchemas :: [EBMLSchema] -> EBMLSchemas
getDocument :: EBMLSchemas -> Get EBMLDocument
getElementHeader :: Get EBMLElementHeader
getElementID :: Get EBMLID
getDataSize :: Get Word64
getElement :: EBMLSchemas -> Get EBMLElement