emurestapi

Media

The Media resource allows multimedia documents associated with a emultimedia record to be retrieved. 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 record
  • resolution - 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 document
  • category - one of the three categories (media, resolution or supplementary) defined earlier indicating how the media is related to the primary document
  • mime type - the MIME type value for the document
  • mime format - the MIME format value for the document
  • media 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}/users/{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/users/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}

Next: Users