External Metadata Advanced 18.3

Caveat

This page is still under construction as MediaHaven 18.3 is not yet released. Release is scheduled for 06 Jul 2018, once release is ready this page can be finalized.

Introduction

Metadata can be provided to MediaHaven in the form of a metadata XML. The XML can be provided as a sidecar XML file or provided in a MediaHaven REST API. The basic version of the external metadata format can be found here: External Metadata Basic.

The following XSD validates the metadata:

Standard Fields

Sidecar (xpath)	Profile	Description	Format
`title`	`Title`	The title of the file
`description`	`Description`	Description about the file
`md5`	`Md5`	The MD5 checksum of the submitted file. If it mismatches with the calculated MD5 checksum during ingest, the file is rejected.
`keywords/keyword`	`Keywords`	Series of categories about the file	MultiItem
`MDProperties/CreationDate`	`CreationDate`	The date and time the file was originally created	EXIF
`MDProperties/rights_owner`	`Rights_Owner`	The name of the (copyright) owner of the file
`MDProperties/Publisher`	`Publisher`	Publisher of the file
`MDProperties/categories/category`	`Categories`	Series of keywords about the file	MultiItem
`MDProperties/Authors/auteur`	`Authors`	Series of authors of the file	MultItem
`MDProperties/<any-tag>`	`<any-tag>`	The user can provide his or her own custom tags as children of the tag `MDProperties`. Namespaced tags are not allowed It is forbidden to use MediaHaven reserved tags names inside `MDProperties`. The reserved fields include the following tags: `type`, `title`, `description`. The full list of the reserved fields in MediaHaven: Metadata Fields.

Advanced Fields

Sidecar (xpath)	Description
`Relations/<relation-type>/ExternalId`	Define relations with this file as subject and the provided references as object by means of an ExternalId. The object of the relation must already exist in MediaHaven with the provided ExternalId. The provided relation type must have been configured in MediaHaven beforehand Namespaced relation types are not allowed
`fragments/fragment`	To create fragments of videos or documents, you can provide a list of `fragment` children under the element `fragments`. The fields below allow for providing some basic metadata fields to the created fragments.
`fragments/fragment/original_start_z`	The start position of the fragment in the file In the case of video or audio: expressed in frames. Calculate the seconds relative to the start of the video, multiply by 25 and round to an integer. For example: 10.40s => 252 In the case of images or documents: the layer or page number, counted from 0.
`fragments/fragment/original_end_z`	The end position of the fragment in the file In the case of video or audio: expressed in frames. Calculate the seconds relative to the start of the video, multiply by 25 and round to an integer. For example: 10.40s => 252 In the case of images or documents: no meaning
`fragments/fragment/title`	The title of the new fragment
`fragments/fragment/description`	The description of the new fragment
`fragments/fragment/keywords/keyword`	A list of keywords about the new fragment
`Technical`	All the technical fields defined in Metadata 18.3#Technical appear under the tag `Technical`.
`Internal`	All the internal fields defined in Metadata 18.3#Internal appear under the tag Internal.
`Administrative`	All the fields defined in Metadata 18.3#Administrative appear under the tag `Administrative`.
`Structural`	All the fields defined in Metadata 18.3#Structural appear under the tag `Structural`.
`RightsManagement`	All the fields defined in Metadata 18.3#RightsManagement appear under the tag `RightsManagement`.

Example

MediaHAVEN_external_metadata

<?xml version="1.0" encoding="UTF-8"?>
<MediaHAVEN_external_metadata>
   <title>Big Buck Bunny, Sunflower version</title>
   <description />
   <OriginalFilename>video.mp4</OriginalFilename>
   <Descriptive>
      <Title>Big Buck Bunny, Sunflower version</Title>
      <RightsOwner>SoundHandler</RightsOwner>
      <Authors>
         <Author>Blender Foundation 2008</Author>
         <Author>Janus Bager Kristensen 2013</Author>
      </Authors>
   </Descriptive>
   <Administrative>
      <OrganisationName>dev</OrganisationName>
      <LastModifiedDate>2018-03-14T06:42:07Z</LastModifiedDate>
      <ArchiveDate>2017:06:21 15:41:10</ArchiveDate>
      <UploadedBy>Rombaut Alexis</UploadedBy>
      <Type>video</Type>
   </Administrative>
   <Technical>
      <OriginalFilename>video.mp4</OriginalFilename>
      <OriginalExtension>mp4</OriginalExtension>
      <FileSize>14423025</FileSize>
      <Md5>04b290c0ec258ad21e36a5fbb777a16c</Md5>
      <MimeType>video/mp4</MimeType>
      <DurationTimeCode>00:00:30.000</DurationTimeCode>
      <StartTimeCode>00:00:00.000</StartTimeCode>
      <EndTimeCode>00:00:30.000</EndTimeCode>
      <DurationFrames>0000000750</DurationFrames>
      <StartFrames>0000000000</StartFrames>
      <EndFrames>0000000750</EndFrames>
      <FragmentDurationTimeCode>00:00:30.000</FragmentDurationTimeCode>
      <FragmentStartTimeCode>00:00:00.000</FragmentStartTimeCode>
      <FragmentEndTimeCode>00:00:30.000</FragmentEndTimeCode>
      <FragmentDurationFrames>0000000750</FragmentDurationFrames>
      <FragmentStartFrames>0000000000</FragmentStartFrames>
      <FragmentEndFrames>0000000750</FragmentEndFrames>
      <VideoCodec>h264 (High) (avc1 / 0x31637661)</VideoCodec>
      <VideoFps>60.0</VideoFps>
      <VideoBitRate>3640000</VideoBitRate>
      <AudioCodec>aac (LC) (mp4a / 0x6134706D)</AudioCodec>
      <AudioChannels>6</AudioChannels>
      <AudioSampleRate>48000</AudioSampleRate>
      <AudioBitRate>192000</AudioBitRate>
      <BitRate>3843000</BitRate>
   </Technical>
   <Internal>
      <MediaObjectId>a861cf066160493aac92fec2a9df76adad5831bc9e60443099732a3b93303066</MediaObjectId>
      <FragmentId>a861cf066160493aac92fec2a9df76adad5831bc9e60443099732a3b9330306681e1e5beb7c042f69cb6d3526753947b</FragmentId>
      <OriginalStatus>completed</OriginalStatus>
      <BrowseStatus>completed</BrowseStatus>
      <ArchiveStatus>on_disk</ArchiveStatus>
      <UploadedById>868b732b-5c74-4f07-8c38-35daf37464f5</UploadedById>
      <OrganisationId>100</OrganisationId>
      <IsInIngestSpace>0</IsInIngestSpace>
      <IsFragment>0</IsFragment>
      <HasKeyframes>0</HasKeyframes>
      <ContainsGeoData>0</ContainsGeoData>
      <PathToKeyframe>http://dev-storage-virtual.mediahaven.com/DEV/a861cf066160493aac92fec2a9df76adad5831bc9e60443099732a3b93303066/keyframes/keyframes_1_1/keyframe1.jpg</PathToKeyframe>
      <PathToKeyframeThumb>http://dev-storage-virtual.mediahaven.com/DEV/a861cf066160493aac92fec2a9df76adad5831bc9e60443099732a3b93303066/keyframes-thumb/keyframes_1_1/keyframe1.jpg</PathToKeyframeThumb>
      <PathToVideo>http://dev-storage-virtual.mediahaven.com/DEV/a861cf066160493aac92fec2a9df76adad5831bc9e60443099732a3b93303066/browse.mp4</PathToVideo>
      <Browses>
         <Browse>
            <PathToKeyframe>http://dev-storage-virtual.mediahaven.com/DEV/a861cf066160493aac92fec2a9df76adad5831bc9e60443099732a3b93303066/keyframes/keyframes_1_1/keyframe1.jpg</PathToKeyframe>
            <PathToKeyframeThumb>http://dev-storage-virtual.mediahaven.com/DEV/a861cf066160493aac92fec2a9df76adad5831bc9e60443099732a3b93303066/keyframes-thumb/keyframes_1_1/keyframe1.jpg</PathToKeyframeThumb>
            <PathToVideo>http://dev-storage-virtual.mediahaven.com/DEV/a861cf066160493aac92fec2a9df76adad5831bc9e60443099732a3b93303066/browse.mp4</PathToVideo>
         </Browse>
      </Browses>
   </Internal>
   <Structural>
        <Collections>
            <Collection>90d1cbac59664289bab50a081174977659601c05b6dd4004b1ab26e04df8c970_3</Collection>
        </Collections>
   </Structural>
   <RightsManagement>
      <Permissions>
         <Read>dd100b7a-efd0-44e3-8816-0905572421da</Read>
         <Write>dd100b7a-efd0-44e3-8816-0905572421da</Write>
         <Export>dd100b7a-efd0-44e3-8816-0905572421da</Export>
         <None>de100b7a-efd0-44e3-8816-0905572421da</None>
         <Read>df100b7a-efd0-44e3-8816-0905572421da</Read>
         <None>d8a8bb26-2ccb-4c3e-809b-3498a520b25b</None>
         <None>df102b7a-efd0-44e3-8816-0905572421da</None>
      </Permissions>
   </RightsManagement>
   <fragments>
      <fragment>
         <title>video.mp4</title>
         <original_start_z>302</original_start_z>
         <original_end_z>355</original_end_z>
         <Internal>
            <FragmentId>a861cf066160493aac92fec2a9df76adad5831bc9e60443099732a3b933030663fb771b5816046a5b135c78e91109ea6</FragmentId>
         </Internal>
      </fragment>
   </fragments>
   <MDProperties>
      <Authors type="list">
         <auteur>Blender Foundation 2008</auteur>
         <auteur>Janus Bager Kristensen 2013</auteur>
      </Authors>
      <RightsOwner>SoundHandler</RightsOwner>
   </MDProperties>
</MediaHAVEN_external_metadata>

Strategy

An advanced feature is the use of the attribute strategy on top level metadata field under MDProperties, for example Title, Description, Authors, RightsOwner.

We have three possible values:

KEEP: Don't overwrite the old value if it is non empty
OVERWRITE:
1. Overwrite the old value for this field
2. This is the default strategy for simple fields which are fields that contain a textual value
MERGE:
- Only applicable to complex fields which are fields that contain sub fields, such as Authors, Keywords and Categories.
- Merge the new sub fields with the existing sub fields
- This is the default strategy for complex fields

Sidecar XML

<?xml version="1.0" encoding="UTF-8"?>
<MediaHAVEN_external_metadata>
   <title strategy="OVERWRITE">Big Buck Bunny, Sunflower version</title>
   <description strategy="KEEP">The best movie ever!</description>
   <MDProperties>
      <Authors type="list" strategy="MERGE">
         <auteur>Blender Foundation 2008</auteur>
      </Authors>
      <RightsOwner type="KEEP">SoundHandler</RightsOwner>
   </MDProperties>
</MediaHAVEN_external_metadata>

Existing Metadata

<?xml version="1.0" encoding="UTF-8"?>
<MediaHAVEN_external_metadata>
   <title>Big Buck Bunny</title>    
   <MDProperties>
      <Authors type="list">
         <auteur>Janus Bager Kristensen 2013</auteur>
      </Authors>
      <RightsOwner>Janus Kristensen</RightsOwner>
   </MDProperties>
</MediaHAVEN_external_metadata>

Resulting Metadata

<?xml version="1.0" encoding="UTF-8"?>
<MediaHAVEN_external_metadata>
   <title>Big Buck Bunny, Sunflower version</title>
   <description>The best movie ever!</description>    
   <MDProperties>
      <Authors type="list">
         <auteur>Blender Foundation 2008</auteur>
         <auteur>Janus Bager Kristensen 2013</auteur>
      </Authors>
      <RightsOwner>Janus Kristensen</RightsOwner>
   </MDProperties>
</MediaHAVEN_external_metadata>