Media

The media types describe images, video, audio and captions: an image's size, a frame rate, a timecode, a subtitle cue, a film's age rating. Each follows its own standard. As every standard type does, each is read only in its canonical text. None is ordered, and none is personal data.

Here a video library makes thumbnails, reads a film's age rating, shows where an edit starts and writes captions:

type FormText = Text {}type NotARating = Failure {    kind: FailureKind.invalid_value}/// A still's thumbnail: scaled to fit a 320-pixel square, never enlarged.function thumbnail(video_still: ImageDimensions) -> ImageDimensions {    var tile: ImageDimensions = ImageDimensions {        width: 320        height: 320    }    return media.fit(video_still, within: tile)}/// The age rating a film's form names.function film_rating(raw: FormText) fails NotARating -> ContentRating {    var typed_rating: ContentRating = attempt text.parse(raw, as: ContentRating) {        malformed: NotARating        rating_of_scheme: NotARating    }    return typed_rating}/// Where an edit starts, as the edit list shows it.function edit_start(edit_point: Timecode) -> PresentationText {    return text.format(edit_point, locale: Locale.en_gb)}/// A caption as a WebVTT file writes it.function caption_text(opening_caption: SubtitleCue) -> FormText {    return FormText(text.from(opening_caption))}

test "a thumbnail fits its tile and is never enlarged" {    var landscape: ImageDimensions = ImageDimensions {        width: 4000        height: 3000    }    var wide_still: ImageDimensions = ImageDimensions {        width: 1000        height: 333    }    var icon: ImageDimensions = ImageDimensions {        width: 200        height: 100    }    assert text.from(thumbnail(landscape)) == "320x240"    assert text.from(thumbnail(wide_still)) == "320x106"    assert thumbnail(icon) == icon}test "a rating is one of its body's categories" {    var given_rating: ContentRating = attempt film_rating("BBFC 12A")    assert given_rating.scheme == ContentRatingScheme.bbfc    assert film_rating("BBFC PG-13") fails NotARating    assert film_rating("12A") fails NotARating}test "a timecode is shown in SMPTE's notation, a cue as WebVTT writes it" {    var edit_point: Timecode = Timecode {        hours: 1        minutes: 10        seconds: 0        frames: 0        rate: FrameRate {            numerator: 30000            denominator: 1001        }        drop_frame: true    }    assert edit_start(edit_point) == "01:10:00;00"    var opening_caption: SubtitleCue = SubtitleCue {        start: 1s        end: 4s        text: "Mind the gap."    }    assert caption_text(opening_caption) == "00:00:01.000 --> 00:00:04.000\nMind the gap."}

Fitting an image into a box

media.fit works as CSS's object-fit: scale-down does, in whole numbers. The side that limits the fit becomes exactly the box's size. The other side is scaled with it and rounded down, never below 1. An image that already fits is kept as it is, never enlarged.

Sizes, ratios and frame rates

• An ImageDimensions and a VideoResolution are a width and a height in whole pixels, from 1 to 2,147,483,647. That is PNG's limit, the largest of the common formats'. Each is written 1920x1080, width first, with a lower-case x. Each is sent as named fields, so nothing reads them the wrong way round, and stored as a column each.
• A VideoResolution has the same shape under its own name. It names a resolution by its pixels, never by a name like "4K", which means both 3840 and 4096 pixels across.
• An AspectRatio is a width and a height, whole numbers from 1, written 16:9. It is held as written, as a Ratio is, so 16:9 and 32:18 are two different values. It is sent as its text and stored as a column each. A cinema's 2.39:1 is written 239:100. A later release can accept decimals without changing any value.
• A FrameRate is a numerator and a denominator, each from 1 to 2,147,483,647, written 30000/1001 or 25/1. The denominator is always written, and the rate is held as written. It is sent as its text and stored as a column each.

Boxes, paper and orientation

• A Rect is an x and a y, each any Decimal, and a width and a height, never below 0. Its text is SVG's viewBox: 0 0 300 200.
• An Insets is a top, right, bottom and left, each never below 0, so a negative margin is refused. Its text is the CSS box model's four sides: 8 16 8 16.
• In both texts each number keeps the places it was given, has no leading zero, and is one space from the next, and every part is always written. Each is sent as named fields and stored as a column per part.
• A PaperSize is one of ISO 216's A0 to A10 and B0 to B10, or ANSI/ASME Y14.1's letter, legal and tabloid, coded A4 or Letter. ISO 269's envelope sizes and ledger (tabloid on its side) are left out.
• An ExifOrientation says how a stored image must be turned to show it upright. Its variants are named for where the stored image's first row and column are seen, as libtiff names TIFF 6.0's values: top_left to left_bottom. They are coded 1 to 8 and sent as that text, as every enum is sent as its code.
• An AltText is one line of an image's text alternative, as WCAG describes it: 1 to 1,000 characters, with no space at either end. An image with nothing to say has none in a field that may be empty, never empty text.

Codecs

A VideoCodec and an AudioCodec are the codec strings the W3C WebCodecs Codec Registry lists, in RFC 6381's form, such as avc1.42001E or opus:

• video: av01, avc1, avc3, hev1, hvc1 and vp09, each with its elements, and vp8;
• audio: mp4a with its elements, flac, mp3, opus, vorbis, ulaw, alaw and the five pcm- forms.

The elements after the first aren't checked further. Case is kept, as the registry writes them.

Timecodes and subtitles

A Timecode is a position in a video as SMPTE ST 12-1 writes it: hours (0 to 23), minutes and seconds (0 to 59) and frames (0 to 119, room for 120 frames a second), with its rate and whether it counts drop_frame. Drop-frame timecode skips some frame labels so that the clock keeps time with a 29.97 frames-a-second video. A timecode has three rules:

• frames_within_rate: its frames are below its rate's frames a second, rounded up to a whole number;
• drop_frame_rate: drop-frame is used only at 30000/1001 and 60000/1001 frames a second, compared by value;
• frame_not_dropped: a drop-frame timecode never names a label that drop-frame skips, frames 0 and 1 (or 0 to 3 at the higher rate) at the start of each minute except every tenth.

Its notation, 01:00:00;00, doesn't say its rate, so a timecode has no single text form. It is sent as its parts, stored as a column per part (its rate in two), and shown in that notation.

A SubtitleCue is a WebVTT cue: a start and an end, each a Duration from the start of the media to the millisecond, and its text, lines with no control character and no blank line. Its rules are start_not_negative, end_after_start and text_without_arrow, which refuses --> in the text. Its canonical text is the cue's timings line, its hours in two digits or more, then a line feed and its text, with no identifier or settings: 00:00:01.000 --> 00:00:04.000 and its text. It is sent as named fields and stored as a column per part.

When you write a Timecode or a SubtitleCue out as a literal, its rules are checked while compiling. A value read from JSON is checked as it is read. One built in code from other values is built with attempt, which fails by the rule it breaks.

Age ratings

A ContentRating is a scheme and a rating, one of that body's categories as it writes them, its rule rating_of_scheme. It is written BBFC 12A or PEGI 16, the body's code read ignoring case. It is sent as that text and stored as a column each.

The bodies are a standard enum, ContentRatingScheme:

• BBFC: U, PG, 12A, 12, 15, 18, R18;
• the MPA, the MPAA's name since 2019: G, PG, PG-13, R, NC-17;
• PEGI: 3, 7, 12, 16, 18;
• ESRB: E, E10+, T, M, AO, RP.

Other bodies, such as USK, the ACB and US television's, come with a later release.