Media
The Media resource allows multimedia documents associated with a emultimedia record to be retrieved and ingested. Each EMu multimedia record can have a number of multimedia documents associated with it. The documents may be images, videos, audios, PDFs, text based documents or indeed anything that can be stored in a file. If multimedia documents are part of a multimedia record then the JSON markup returned for the multimedia record will contain links to the associated multimedia documents.
Multimedia documents associated with an EMu multimedia record fit into one of three categories, namely:
media- the primary multimedia document described by the EMu multimedia recordresolution- different resolutions of the primary document. For example there may be a thumbnail sized resolution used to display a thumbnail of the primary image on the web.supplementary- an optional series of media documents related to the primary document. Supplementary multimedia documents contain different content from the primary document. For example a supplementary image document may contain a frame from a video based primary document. A text supplementary document may contain a transcript of the audio of the video.
Each of the above categories is represented by a field in an EMu multimedia record. The table below lists the field names:
| Category | Field Name |
|---|---|
| media | MulMediaRef |
| resolution | DocMediaRef_tab |
| supplementary | SupMediaRef_tab |
The JSON fragment of an EMu multimedia record below shows the media links for the multimedia documents associated with the record.
{
"id": "emu:/museum/emultimedia/1",
"version": 1,
"data": {
"SummaryData": "Dr Christopher L Johnson (image/jpeg)",
"MulMediaRef": {
"id": "emu:/museum/media/1:media:image:jpeg:dcp00101.jpg",
"@controls": {
"self": {
"href": "http://dorrit.melbourne.axiell.com:8088/museum/media/1:media:image:jpeg:dcp00101.jpg"
}
}
},
"DocMediaRef_tab": [
{
"id": "emu:/museum/media/1:resolution:image:jpeg:dcp00101.jpg",
"@controls": {
"self": {
"href": "http://dorrit.melbourne.axiell.com:8088/museum/media/1:resolution:image:jpeg:dcp00101.jpg"
}
}
},
{
"id": "emu:/museum/media/1:resolution:image:jpeg:dcp00101.thumb.jpg",
"@controls": {
"self": {
"href": "http://dorrit.melbourne.axiell.com:8088/museum/media/1:resolution:image:jpeg:dcp00101.thumb.jpg"
}
}
},
{
"id": "emu:/museum/media/1:resolution:image:jpeg:dcp00101.600x800.jpg",
"@controls": {
"self": {
"href": "http://dorrit.melbourne.axiell.com:8088/museum/media/1:resolution:image:jpeg:dcp00101.600x800.jpg"
}
}
},
{
"id": "emu:/museum/media/1:resolution:image:jpeg:dcp00101.300x400.jpg",
"@controls": {
"self": {
"href": "http://dorrit.melbourne.axiell.com:8088/museum/media/1:resolution:image:jpeg:dcp00101.300x400.jpg"
}
}
}
]
}
}
The fragment shows the primary multimedia document link in the MulMediaRef property and various resolutions in the DocMediaRef_tab property. The first two resolution links are reserved for the primary media document (a copy of the MulMediaRef property) and the optional thumbnail media document. Other resolutions then follow on.
The format of a multimedia document link is emu:/{tenant}/media/{mediaid}. The mediaid identifier may be broken down into five components, namely {multimedia identifier}:{category}:{mime type}:{mime format}:{media identifier}, with the following meaning:
multimedia identifier- the identifier (key number) of the EMu multimedia record associated with the multimedia documentcategory- one of the three categories (media,resolutionorsupplementary) defined earlier indicating how the media is related to the primary documentmime type- the MIME type value for the documentmime format- the MIME format value for the documentmedia identifier- label identifying the specific media resource
For example the mediaid emu:/museum/media/1:media:image:jpeg:dcp00101.jpg indicates the link is associated with the EMu multimedia record with key number 1 (emu:/museum/emultimedia/1). It is the primary multimedia document and the content type is image/jpeg. The media identifier is dcp00101.jpg.
The media resource uses the same access methods to retrieve multimedia documents as that used by EMu. The ServerMediaPath registry entry is honoured including the exec extension allowing third party systems to be integrated.
In order to retrieve a media resource display permission is required for the associated EMu multimedia record. Permissions are not allocated on individual multimedia documents, rather the permissions granted to the associated multimedia record are used.
The following requests are available for the media resource.
Retrieve
GET /{tenant}/media/{mediaid}
The GET method retrieves a single multimedia document from the EMu multimedia repository. The format of the mediaid component is covered in the section above. The multimedia document identifier is streamed back using the HTTP chunked transfer encoding. The chunked encoding enables videos and audios to begin playing before the complete contents have been retrieved from the EMu server.
The multimedia document is returned as an octet stream with the Content-Type header set to the MIME type of the stream. The Prefer header used to control the level of Mason markup applied is ignored by this request as only a stream of bytes is returned.
A 200 status is returned along with the multimedia document as an octet stream for successful requests.
Example URI
GET /tenant/media/347:media:video:mp4:Alvinella%20pompejana.mp4
Headers
Authorization: Bearer {token}
Prefer: representation=minimal
Response 200
HTTP chunked transfer encoding of octet stream of video
Response Headers
Content-Type: video/mp4
Authorization: Bearer {token}
Ingest
PUT /{tenant}/media/{id}
The PUT method allows media (images, videos, audio, documents) to be ingested and associated with a multimedia record. The multimedia record must exist before any media can be attached to it. The id component of the request is the IRN of the multimedia record with which the media is associated. To ingest media you must have update privileges on the multimedia record defined by the supplied id.
There are two methods available for ingesting media. The first method requires the media file to exist on the server machine, generally in a holding area. The request must contain a JSON object with a single property called “file”. The value of the property is the full path to the media file to be ingested. An example is:
{
"file": "/tmp/images/01c copy.JPG"
}
The ingestion process will copy the supplied file to a temporary area where any resolutions are generated and profile data extracted. The master file, thumbnail and any resolutions are then copied into the multimedia repository and the multimedia record updated with the new media information. Any temporary files are then deleted.
The second method used to ingest data allows the media file to be uploaded via the HTTP file upload mechanism to the server and then processed. In this case the request must use the HTTP multipart mode. Only a single file at a time can be uploaded.
Where possible the first form of ingestion is recommended, that is with the media file on the server (maybe on a shared area) as the HTTP multipart mode is very slow when uploading large files.
It is also possible to associate a URL or a general Reference (e.g. ISBN) with a multimedia record rather than a media file. To associate a URL the “url” property is used with the value containing the URL. For example:
{
"url": "http://www.google.com"
}
Where a general Reference is required the “reference” property along with the reference value are used. For example:
{
"reference": "isbn: 978-92-95055-02-5"
}
A 200 status is returned along with the updated multimedia record for successful ingestions.
Example URI
PUT /tenant/media/10254
Headers
Content-Type: application/json
Authorization: Bearer {token}
Prefer: representation=minimal
Body
{
"file": "/tmp/images/001_MIA_GL.6_042-reduced.tif"
}
Response 200
Full Mason marked up multimedia record with IRN 10254.
Response Headers
Content-Type: application/vnd.mason+json; charset=UTF-8
Authorization: Bearer {token}