Media API

API for media streaming and media transcoding.

The Media API follows the IIIF Image API:

[IIIF Image API]
IIIF Image API 2.1. Edited by Michael Appleby, Tom Crane, Robert Sanderson, Jon Stroop, and Simeon Warner. Copyright © 2012-2016 Editors and contributors. Published by the IIIF Consortium under the CC-BY license.

A/V extensions are based on IIIF A/V Technical Specification Group.

Contents

Media File Request

GET {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}

Streams a media file from a file system according to a repository name and a unique identifier. Supports HTTP 1.1 Range Requests.

Examples
Audio
/media/a5-1/a5:/test-wav
Image
/media/a5-2/a5:/00-0000-0000-0000-0C8C-9
Video
/media/a5-1/a5:demo-mp4-1mb
PDF
/media/a5-1/a5:/test-pdf
Text
/media/a5-1/a5:test-txt
XML
/media/a5-1/a5:test-xml

Repository {repository}

GET {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}

The name of the repository.

Example Description
/media /a5-1/ a5:/test-pdf Returns a file from repository "a5-1".
/media /a5-2/ a5:/00-0000-0000-0000-0C8C-9 Returns a file from repository "a5-2".

Identifier [{prefix}/]{identifier}

GET {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}

The unique identifier of the file.

Example Description
/media/a5-1/a5:/test-pdf Returns a file by DOI "a5:/test-pdf".
/media/a5-1/a5:demo-mp4-1mb Returns a file by UUID "a5:demo-mp4-1mb".

Media Manipulation Request

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/{filter}/{quality}.{format}

Streams a media file in a manipulated form. Returns HTTP 202 if manipulation is in progress, HTTP 200 otherwise.

Section {section}

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/{filter}/{quality}.{format}

Extracts a time section from a media file.

Example Description
The complete media file is returned without any cropping. "full"
Extracts a time section from a media file. The examples seek to second 20 and extract a time section with 20 seconds of length. offset[,length]

Region {region}

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/{filter}/{quality}.{format}

Extracts an image region from a media file.

Example Description
The complete image is returned without any cropping. "full"
Offset x, offset y, width w, and height h of the region relative to the top-left of an image. x,y,w,h

Size {size}

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/{filter}/{quality}.{format}

Scales an image to a specific size.

Example Description
/media/a5-2/a5:/00-0000-0000-0000-0C8C-9/full/full/full/0/none/default.jpg Returns a image file in its original size. "full"
/media/a5-2/a5:/00-0000-0000-0000-0C8C-9/full/full /500,/ 0/none/default.jpg The image is scaled so that its width is equal to w, and the height will be a calculated value that maintains the aspect ratio. w,
/media/a5-2/a5:/00-0000-0000-0000-0C8C-9/full/full /,200/ 0/none/default.jpg The image is scaled so that its height is equal to h, and the width will be a calculated value that maintains the aspect ratio. ,h
/media/a5-2/a5:/00-0000-0000-0000-0C8C-9/full/full/ 300,100 /0/none/default.jpg The width and height of the returned image are equal to w and h. The aspect ratio of the returned image may be different resulting in a distorted image. w,h

Rotation {rotation}

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/{filter}/{quality}.{format}

Rotates an image or video file.

Example Description
IMAGE: VIDEO: 0, 90, 180, or 270 of clockwise rotation. "0"|"90"|"180"|"270"

Filter {filter}

Applies filters to the input media file.

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/{filter}/{quality}.{format}

Example Description
IMAGE: /media/a5-1/a5:/large-tif/full/full/full/0 /none/ default.jpg No filter is applied. "none"
Media file is returned in grayscale. "gray"

Quality {quality}

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/{filter}/{quality}.{format}

Defines the compression rate / quality of the returned media file.

Example Description
"default" does not change the quality / compression rate of the media file and returns it as it is.
In combination with {format} conversion, a default compression rate is choosen.		 "default"
"high" returns the media file in the highest quality possible.
{quality} is useful in combination with format conversion, for example, if the file on the file system is a TIFF file and you want to return it as a high quality JPEG.		 "high"
"medium" returns the media file in medium quality with reduced size. "medium"
"low" reduces the size of the media file as much as possible, probably leading to low quality. "low"

For PDF, Text, and XML as well as for image, audio and video formats that do not support compression or different compression rates, {quality} has no effect.

Format {format}

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/{filter}/{quality}.{format}

Defines the format of the returned media file.

Supported formats
Example Description
Output format expressed as an extension at the end of the URI.
Output format expressed as an extension at the end of the URI.
Output format expressed as an extension at the end of the URI.

For PDF and Text, {format} has no effect.

Cross Media Request

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/{filter}/{quality}.{format}

Streams a media file in a representation different from its original media type.

Video to Audio

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/{filter}/{quality}.{format}

Extracts the audio channels from a video file.

Example Description
/media/a5-1/a5:demo-mp4-50mb/full/full/full/180/none/default. mp3 Example returns the audio channels in format "mp3" from a MP4 video file. "(aiff|mp3|wav|webm)"
/media/a5-1/a5:demo-mp4-1mb/full/full/full/180/none/default. wav Example returns the audio channels in format "wav" from a MP4 video file. "(aiff|mp3|wav|webm)"

Audio to Image

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/spectrum/{quality}.{format}

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/waveform/{quality}.{format}

Returns waveform and spectrum images.

Example Description
Examples return a spectrum image, size "12000x150px", in format "png".
Examples return a waveform image, size "12000x150px", in format "png".

Video to Image

GET|HEAD {scheme}://{server}/media/{repository}/[{prefix}/]{identifier}/{section}/{region}/{size}/{rotation}/thumbnail/{quality}.{format}

Extracts a thumbnail image from a video at a specific position.

Example Description
/media/a5-1/a5:demo-mp4-1mb/3,/full/500,/0/ thumbnail /default.jpg Returns a thumbnail image at time position "3sec".