Data.ByteString.IsoBaseFileFormat.Boxes.Box

Definition of the most basic element in an ISOBMFF file: a box. See Chapter 4 in the standard document. A box is a container with a type, a size, possible some data and some nested boxes. The standard defines - among other characteristics - what boxes exist, what data they contain and how they are nested into each other. This library tries to capture some of these characteristics using modern Haskell type system features to provide compile checks for (partial) standard compliance.

Basic Types and classes

class BoxRules t

A class that describes (on the type level) how a box can be nested into other boxes (see Boxes).

Associated Types

type RestrictedTo t :: Maybe [k]

List of boxes that this box can be nested into.

type IsTopLevelBox t :: Bool

If the box is also allowed 'top-level' i.e. in the file directly, not nested in an other box.

type RequiredNestedBoxes t :: [k]

Describes which nested boxes MUST be present in a box using boxes.

type GetCardinality t (c :: k) :: Cardinality

Describes how many times a box should be present in a container (-box).

data Cardinality

Describes how many times a box should be present in a container.

Constructors

AtMostOnce

ExactlyOnce

OnceOrMore

class BoxRules t => IsBoxType t where

Convert type level box types to values

Minimal complete definition

toBoxType

Methods

toBoxType :: proxy t -> BoxType

Instances

(BoxRules Symbol t, KnownSymbol t) => IsBoxType Symbol t

Methods

toBoxType :: proxy t -> BoxType

class IsBoxContent a where

Types that go into a box. A box content is a piece of data that can be reused in different instances of IsBox. It has no BoxType and hence defines no box.

Minimal complete definition

boxSize, boxBuilder

Methods

boxSize :: a -> BoxSize

boxBuilder :: a -> Builder

Instances

IsBoxContent ()

An empty box content can by represented by () (i.e. unit).

Methods

boxSize :: () -> BoxSize

boxBuilder :: () -> Builder

IsBoxContent FullBoxHeader

Methods

boxSize :: FullBoxHeader -> BoxSize

boxBuilder :: FullBoxHeader -> Builder

IsBoxContent BoxTypeExtension

Methods

boxSize :: BoxTypeExtension -> BoxSize

boxBuilder :: BoxTypeExtension -> Builder

IsBoxContent FourCc

Methods

boxSize :: FourCc -> BoxSize

boxBuilder :: FourCc -> Builder

IsBoxContent BoxType

Methods

boxSize :: BoxType -> BoxSize

boxBuilder :: BoxType -> Builder

IsBoxContent BoxSizeExtension

Methods

boxSize :: BoxSizeExtension -> BoxSize

boxBuilder :: BoxSizeExtension -> Builder

IsBoxContent BoxSize

Methods

boxSize :: BoxSize -> BoxSize

boxBuilder :: BoxSize -> Builder

IsBoxContent FileType

Methods

boxSize :: FileType -> BoxSize

boxBuilder :: FileType -> Builder

IsBoxContent MediaData

Methods

boxSize :: MediaData -> BoxSize

boxBuilder :: MediaData -> Builder

IsBoxContent ProgressiveDownloadInformation

Methods

boxSize :: ProgressiveDownloadInformation -> BoxSize

boxBuilder :: ProgressiveDownloadInformation -> Builder

IsBoxContent Skip

Methods

boxSize :: Skip -> BoxSize

boxBuilder :: Skip -> Builder

KnownNat bits => IsBoxContent (BoxFlags Nat bits)

Get the number of bytes required to store a number of bits.

Methods

boxSize :: BoxFlags Nat bits -> BoxSize

boxBuilder :: BoxFlags Nat bits -> Builder

IsBoxContent (Box t t1)

Methods

boxSize :: Box t t1 -> BoxSize

boxBuilder :: Box t t1 -> Builder

(IsBoxContent p, IsBoxContent c) => IsBoxContent (Extend p c)

Methods

boxSize :: Extend p c -> BoxSize

boxBuilder :: Extend p c -> Builder

IsBoxContent (UnverifiedBoxes x t bs)

Methods

boxSize :: UnverifiedBoxes x t bs -> BoxSize

boxBuilder :: UnverifiedBoxes x t bs -> Builder

(IsBoxType x t, ValidBoxes x t bs) => IsBoxContent (Boxes x t bs)

To be nested into a box, Boxes must be an instance of IsBoxContent. This instance concatenates all nested boxes.

Methods

boxSize :: Boxes x t bs -> BoxSize

boxBuilder :: Boxes x t bs -> Builder

data Extend a b

Box content composed of box contents a and b.

Constructors

Extend a b

Instances

(IsBoxContent p, IsBoxContent c) => IsBoxContent (Extend p c)

Methods

boxSize :: Extend p c -> BoxSize

boxBuilder :: Extend p c -> Builder

Boxes

box :: forall t c. (IsBoxType t, IsBoxContent c) => c -> Box t

Create a Box with a StdType FourCc type.

emptyBox :: forall t. IsBoxType t => Box t

An empty box. This is for boxes without fields. All these boxes contain is their obligatory BoxHeader possibly nested boxes.

data Box b where

A type that wraps the contents of a box and the box type.

Constructors

Box :: (IsBoxType t, IsBoxContent c) => BoxType -> c -> Box t

Instances

IsBoxContent (Box t t1)

Methods

boxSize :: Box t t1 -> BoxSize

boxBuilder :: Box t t1 -> Builder

Box Size and Type

data BoxSize

The size of the box. If the size is limited to a (fixed) value, it can be provided as a Word64 which will be represented as either a 32bit compact size or as 64 bit largesize. If UnlimitedSize is used, the box extends to the end of the file.

Constructors

UnlimitedSize

BoxSize Word64

Instances

Eq BoxSize

Methods

(==) :: BoxSize -> BoxSize -> Bool

(/=) :: BoxSize -> BoxSize -> Bool

Num BoxSize

Methods

(+) :: BoxSize -> BoxSize -> BoxSize

(-) :: BoxSize -> BoxSize -> BoxSize

(*) :: BoxSize -> BoxSize -> BoxSize

negate :: BoxSize -> BoxSize

abs :: BoxSize -> BoxSize

signum :: BoxSize -> BoxSize

fromInteger :: Integer -> BoxSize

Show BoxSize

Methods

showsPrec :: Int -> BoxSize -> ShowS

show :: BoxSize -> String

showList :: [BoxSize] -> ShowS

IsBoxContent BoxSize

Methods

boxSize :: BoxSize -> BoxSize

boxBuilder :: BoxSize -> Builder

data BoxSizeExtension

The BoxSize can be > 2^32 in which case an BoxSizeExtension must be added after the type field.

Constructors

BoxSizeExtension BoxSize

Instances

IsBoxContent BoxSizeExtension

Methods

boxSize :: BoxSizeExtension -> BoxSize

boxBuilder :: BoxSizeExtension -> Builder

data BoxType

A box has a type, this is the value level representation for the box type.

Constructors

StdType FourCc

FourCc can be used as boxType in Box, standard four letter character code, e.g. ftyp

CustomBoxType String

CustomBoxType defines custom boxTypes in Boxes.

Instances

Eq BoxType

Methods

(==) :: BoxType -> BoxType -> Bool

(/=) :: BoxType -> BoxType -> Bool

Show BoxType

Methods

showsPrec :: Int -> BoxType -> ShowS

show :: BoxType -> String

showList :: [BoxType] -> ShowS

IsBoxContent BoxType

Methods

boxSize :: BoxType -> BoxSize

boxBuilder :: BoxType -> Builder

newtype FourCc

A type containin a printable four letter character code.

Constructors

FourCc (Char, Char, Char, Char)

Instances

Eq FourCc

Methods

(==) :: FourCc -> FourCc -> Bool

(/=) :: FourCc -> FourCc -> Bool

Show FourCc

Methods

showsPrec :: Int -> FourCc -> ShowS

show :: FourCc -> String

showList :: [FourCc] -> ShowS

IsString FourCc

Methods

fromString :: String -> FourCc

IsBoxContent FourCc

Methods

boxSize :: FourCc -> BoxSize

boxBuilder :: FourCc -> Builder

data BoxTypeExtension

When using custom types extra data must be written after the extra size information. Since the box type and the optional custom box type are not guaranteed to be consequtive, this type handles the second part seperately.

Constructors

BoxTypeExtension BoxType

Instances

IsBoxContent BoxTypeExtension

Methods

boxSize :: BoxTypeExtension -> BoxSize

boxBuilder :: BoxTypeExtension -> Builder

Type-safe box composition

data ParentBox b where

A ParentBox is a Box but without it's children. It has no IsBoxContent instance, and it must be converted to a real Box using boxes. This is to prevent creation of boxes with invalid children.

Constructors

ParentBox :: (IsBoxType t, IsBoxContent c) => BoxType -> c -> ParentBox t

parentBox :: forall t c. (IsBoxType t, IsBoxContent c) => c -> ParentBox t

A parent box. Similar to box but for ParentBoxes.

emptyParentBox :: forall t. IsBoxType t => ParentBox t

An empty parent box. This is for boxes without fields. All these boxes contain is their obligatory BoxHeader possibly nested boxes.

boxes :: (IsBoxType t, IsBoxContent (Boxes t ts)) => ParentBox t -> Boxes t ts -> Box t

A box that may contain nested boxes. The nested boxes are type checked to be valid in the container box. This results in a container-box with only valid and all required child boxes. This is checked by the type system. It accept a ParentBox and the nested Boxes and returns a Box, if the type checker is convinced that the parent box and the nested boxes are valid.

(^-) :: (IsBoxType t, IsBoxContent (Boxes t ts)) => ParentBox t -> Boxes t ts -> Box t infixr 1

An operator for starting a Boxes from the parent box.

Example: > xxx :: Box "moov" > xxx = movieBox > ^- Nested (movieHeaderBox (MovieHeader ...)) > :- (trackBox > ^- Nested (trackHeaderBox (TrackHeader ...)) > :- trackReferenceBox (TrackReference ...) > :- trackGroupingIndication (TrackGroupingInd ...))

data Boxes cont boxTypes where

A heterogenous collection of child boxes for a parent box wiht type cont.

Constructors

Nested :: IsBoxType t => Box t -> Boxes c '[t]

(:-) :: IsBoxType t => Boxes c ts -> Box t -> Boxes c (t ': ts) infixl 2

Instances

(IsBoxType x t, ValidBoxes x t bs) => IsBoxContent (Boxes x t bs)

To be nested into a box, Boxes must be an instance of IsBoxContent. This instance concatenates all nested boxes.

Methods

boxSize :: Boxes x t bs -> BoxSize

boxBuilder :: Boxes x t bs -> Builder

newtype UnverifiedBoxes t ts

An internal wrapper type around Boxes for the IsBoxContent instance. Since the IsBoxContent instance recursivly deconstructs a Boxes the constraints for the validity ValidBoxes cannot be asserted. To circumvent this the IsBoxContent instance for Boxes delegates to the instance of UnverifiedBoxes, which has no ValidBoxes constraint in the instance head.

Constructors

UnverifiedBoxes (Boxes t ts)

Instances

IsBoxContent (UnverifiedBoxes x t bs)

Methods

boxSize :: UnverifiedBoxes x t bs -> BoxSize

boxBuilder :: UnverifiedBoxes x t bs -> Builder

Type level consistency checks

type ValidBoxes t ts = (AllAllowedIn t ts ~ True, HasAllRequiredBoxes t (RequiredNestedBoxes t) ts ~ True, CheckTopLevelOk t ~ True)

A type-level check that uses BoxRules to check that the contained boxes are standard conform.

type family AllAllowedIn (container :: k) (boxes :: [k]) :: Bool where ...

A type function to check that all nested boxes are allowed in the container.

Equations

AllAllowedIn c '[] = True

AllAllowedIn c (t ': ts) = If (CheckAllowedIn c t (RestrictedTo t)) (AllAllowedIn c ts) (TypeError (NotAllowedMsg c t))

type family CheckAllowedIn (c :: k) (t :: k) (a :: Maybe [k]) :: Bool where ...

Equations

CheckAllowedIn c t Nothing = True

CheckAllowedIn c t (Just rs) = Find c rs

type NotAllowedMsg c t = (((((Text "Boxes of type: " :<>: ShowType c) :<>: Text " may not contain boxes of type ") :<>: ShowType t) :$$: ((Text "Valid containers for " :<>: ShowType t) :<>: Text " boxes are: ")) :$$: ShowType (RestrictedTo t)) :$$: (ShowType t :<>: If (IsTopLevelBox c) (Text " boxes may appear top-level in a file.") (Text " boxes must be nested."))

The custom (type-) error message for AllAllowedIn.

type family HasAllRequiredBoxes (c :: k) (req :: [k]) (nested :: [k]) :: Bool where ...

Check that all required boxes have been nested.

Equations

HasAllRequiredBoxes c '[] nested = True

HasAllRequiredBoxes c (r ': restReq) nested = If (Find r nested) (HasAllRequiredBoxes c restReq nested) (TypeError (MissingRequired c r nested))

type IsSubSet base sub = Intersection base sub == sub

type MissingRequired c r nested = ((((Text "Boxes of type: " :<>: ShowType c) :<>: Text " require these nested boxes: ") :<>: ShowType (RequiredNestedBoxes c)) :$$: (Text "but only these box types were nested: " :<>: ShowType nested)) :$$: (Text "e.g. this type is missing: " :<>: ShowType r)

The custom (type-) error message for HasAllRequiredBoxes.

type family CheckTopLevelOk (t :: k) :: Bool where ...

Check that the box may appear top-level.

Equations

CheckTopLevelOk t = IsTopLevelBox t || TypeError (NotTopLevenError t)

type NotTopLevenError c = ((Text "Boxes of type " :<>: ShowType c) :<>: Text " MUST be nested inside boxes of these types: ") :$$: ShowType (RestrictedTo c)

The custom (type-) error message indicating that a box may not appear top-level.

Full Boxes

type FullBox t = Extend FullBoxHeader t

A Box with version and branding information

fullBox :: (IsBoxType t, IsBoxContent c) => BoxVersion -> BoxFlags 24 -> c -> Box t

Create a FullBox from a FourCc StdType and the nested box content.

data FullBoxHeader

The additional header with version and branding information

Constructors

FullBoxHeader BoxVersion (BoxFlags 24)

Instances

IsBoxContent FullBoxHeader

Methods

boxSize :: FullBoxHeader -> BoxSize

boxBuilder :: FullBoxHeader -> Builder

newtype BoxVersion

The box version (in a FullBox) is a single byte

Constructors

BoxVersion Word8

newtype BoxFlags bits

In addition to a BoxVersion there can be 24 bits for custom flags etc in a FullBox.

Constructors

BoxFlags Integer

Instances

Eq (BoxFlags k bits)

Methods

(==) :: BoxFlags k bits -> BoxFlags k bits -> Bool

(/=) :: BoxFlags k bits -> BoxFlags k bits -> Bool

Num (BoxFlags k bits)

Methods

(+) :: BoxFlags k bits -> BoxFlags k bits -> BoxFlags k bits

(-) :: BoxFlags k bits -> BoxFlags k bits -> BoxFlags k bits

(*) :: BoxFlags k bits -> BoxFlags k bits -> BoxFlags k bits

negate :: BoxFlags k bits -> BoxFlags k bits

abs :: BoxFlags k bits -> BoxFlags k bits

signum :: BoxFlags k bits -> BoxFlags k bits

fromInteger :: Integer -> BoxFlags k bits

Show (BoxFlags k bits)

Methods

showsPrec :: Int -> BoxFlags k bits -> ShowS

show :: BoxFlags k bits -> String

showList :: [BoxFlags k bits] -> ShowS

KnownNat bits => Bits (BoxFlags Nat bits)

Methods

(.&.) :: BoxFlags Nat bits -> BoxFlags Nat bits -> BoxFlags Nat bits

(.|.) :: BoxFlags Nat bits -> BoxFlags Nat bits -> BoxFlags Nat bits

xor :: BoxFlags Nat bits -> BoxFlags Nat bits -> BoxFlags Nat bits

complement :: BoxFlags Nat bits -> BoxFlags Nat bits

shift :: BoxFlags Nat bits -> Int -> BoxFlags Nat bits

rotate :: BoxFlags Nat bits -> Int -> BoxFlags Nat bits

zeroBits :: BoxFlags Nat bits

bit :: Int -> BoxFlags Nat bits

setBit :: BoxFlags Nat bits -> Int -> BoxFlags Nat bits

clearBit :: BoxFlags Nat bits -> Int -> BoxFlags Nat bits

complementBit :: BoxFlags Nat bits -> Int -> BoxFlags Nat bits

testBit :: BoxFlags Nat bits -> Int -> Bool

bitSizeMaybe :: BoxFlags Nat bits -> Maybe Int

bitSize :: BoxFlags Nat bits -> Int

isSigned :: BoxFlags Nat bits -> Bool

shiftL :: BoxFlags Nat bits -> Int -> BoxFlags Nat bits

unsafeShiftL :: BoxFlags Nat bits -> Int -> BoxFlags Nat bits

shiftR :: BoxFlags Nat bits -> Int -> BoxFlags Nat bits

unsafeShiftR :: BoxFlags Nat bits -> Int -> BoxFlags Nat bits

rotateL :: BoxFlags Nat bits -> Int -> BoxFlags Nat bits

rotateR :: BoxFlags Nat bits -> Int -> BoxFlags Nat bits

popCount :: BoxFlags Nat bits -> Int

KnownNat bits => IsBoxContent (BoxFlags Nat bits)

Get the number of bytes required to store a number of bits.

Methods

boxSize :: BoxFlags Nat bits -> BoxSize

boxBuilder :: BoxFlags Nat bits -> Builder

boxFlagBitMask :: KnownNat bits => BoxFlags bits -> Integer

Internal function that creates a bit mask with all bits in a BoxFlags set to 1.

cropBits :: KnownNat bits => BoxFlags bits -> BoxFlags bits

Internal function that masks-out all bits higher than bits.