Rich Media Profiles

CrookedNumber edited this page Sep 26, 2014 · 8 revisions

Summary

Rich media document types (and correspondingly: profiles) are very similar to each other. As such it made sense to create a "media item" profile and make all more specific profiles (audio, video, image) the descendent of the media profile.

Media Profile Definition

Canonical URL: https://api.pmp.io/profiles/media

{
  "version" : "1.0"
, "attributes" : {  
    "guid"        : "99cd1ff6-4bee-400b-a5a0-837e6341662d"
  , "title"       : "Media Profile"
  , "valid"       : { "from" : "2013-02-11T13:21:31.598Z"
                    , "to"   : "3013-05-11T13:21:31.598Z"}
  }
, "items" : []      
, "links" : {
    "profile"      : [ { "href" : "http://api.pmp.io/profiles/profile"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "extends"      : [ { "href" : "http://api.pmp.io/profiles/base"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "self"         : [ { "href" : "http://api.pmp.io/docs/99cd1ff6-4bee-400b-a5a0-837e6341662d"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "documentation": [ { "href" : "https://github.com/publicmediaplatform/pmpdocs/wiki/Rich-Media-Profiles"
                       , "type" : "text/html"}]
  , "schema"       : [ { "href"  : "http://api.pmp.io/schemas/media", 
                       , "scope" : "update", "type" : "application/schema+json"} 
                       }
                     ]
  , "alternate"    : [ { "href" : "http://api.pmp.io/profiles/media" }]
  , "edit-form"    : [ { "href" : "http://api.pmp.io/docs-validator", "type" :   "application/json"}]
  }  
, "error" : {OBJECT}
}

Media Profile's Fields

  • enclosure: required. Points to the binary file of the media asset. The enclosures array MUST have at least one item in it to be functional, but it CAN also have multiple. Providing multiple enclosures can be useful to: provide multiple crops for an image or provide audio/video in multiple codecs.
    • enclosure/href : URL pointing to the binary file
    • enclosure/type : MIME type of the binary file
    • enclosure/meta : additional information that is typically different for each sub-media-type (audio, video, image)

Audio Profile Definition

Canonical URL: https://api.pmp.io/profiles/audio

{
  "version" : "1.0"
, "attributes" : {  
    "guid"        : "ef7f170b-4900-4a20-8b77-3142d4ac07ce"
  , "title"       : "Audio Profile"
  , "valid"       : { "from" : "2013-02-11T13:21:31.598Z"
                    , "to"   : "3013-05-11T13:21:31.598Z"}
  }
, "items" : []      
, "links" : {
    "profile"      : [ { "href" : "http://api.pmp.io/profiles/profile"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "extends"      : [ { "href" : "http://api.pmp.io/profiles/media"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "self"         : [ { "href" : "http://api.pmp.io/docs/ef7f170b-4900-4a20-8b77-3142d4ac07ce"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "documentation": [ { "href" : "https://github.com/publicmediaplatform/pmpdocs/wiki/Rich-Media-Profiles"
                       , "type" : "text/html"}]
  , "schema"       : [ { "href"  : "http://api.pmp.io/schemas/audio", 
                       , "scope" : "update", "type" : "application/schema+json"} 
                       }
                     ]
  , "alternate"    : [ { "href" : "http://api.pmp.io/profiles/audio" }]
  , "edit-form"    : [ { "href" : "http://api.pmp.io/docs-validator", "type" :   "application/json"}]
  }  
, "error" : {OBJECT}
}

Audio Profile's Fields

  • enclosure/meta's sub-fields :
    • codec : audio codec of the binary file.
    • format : audio format of the binary file.
    • duration : duration of the audio.

Video Profile Definition

Canonical URL: https://api.pmp.io/profiles/video

{
  "version" : "1.0"
, "attributes" : {  
    "guid"        : "85115aa1-df35-4324-9acd-2bb261f8a541"
  , "title"       : "Video Profile"
  , "valid"       : { "from" : "2013-02-11T13:21:31.598Z"
                    , "to"   : "3013-05-11T13:21:31.598Z"}
  }
, "items" : []      
, "links" : {
    "profile"      : [ { "href" : "http://api.pmp.io/profiles/profile"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "extends"      : [ { "href" : "http://api.pmp.io/profiles/media"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "self"         : [ { "href" : "http://api.pmp.io/docs/85115aa1-df35-4324-9acd-2bb261f8a541"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "documentation": [ { "href" : "https://github.com/publicmediaplatform/pmpdocs/wiki/Rich-Media-Profiles"
                       , "type" : "text/html"}]
  , "schema"       : [ { "href"  : "http://api.pmp.io/schemas/video", 
                       , "scope" : "update", "type" : "application/schema+json"} 
                       }
                     ]
  , "alternate"    : [ { "href" : "http://api.pmp.io/profiles/video" }]
  , "edit-form"    : [ { "href" : "http://api.pmp.io/docs-validator", "type" :   "application/json"}]
  }  
, "error" : {OBJECT}
}

Video Profile's Fields

  • enclosure/meta's sub-fields :
    • codec : video codec of the binary file.
    • format : video format of the binary file.
    • duration : duration of the video.

Image Profile Definition

Canonical URL: https://api.pmp.io/profiles/image

{
  "version" : "1.0"
, "attributes" : {  
    "guid"        : "5f4fe868-5065-4aa2-86e6-2387d2c7f1b6"
  , "title"       : "Video Profile"
  , "valid"       : { "from" : "2013-02-11T13:21:31.598Z"
                    , "to"   : "3013-05-11T13:21:31.598Z"}
  }
, "items" : []      
, "links" : {
    "profile"      : [ { "href" : "http://api.pmp.io/profiles/profile"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "extends"      : [ { "href" : "http://api.pmp.io/profiles/media"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "self"         : [ { "href" : "http://api.pmp.io/docs/5f4fe868-5065-4aa2-86e6-2387d2c7f1b6"
                       , "type" : "application/vnd.pmp.collection.doc+json" }]
  , "documentation": [ { "href" : "https://github.com/publicmediaplatform/pmpdocs/wiki/Rich-Media-Profiles"
                       , "type" : "text/html"}]
  , "schema"       : [ { "href"  : "http://api.pmp.io/schemas/image", 
                       , "scope" : "update", "type" : "application/schema+json"} 
                       }
                     ]
  , "alternate"    : [ { "href" : "http://api.pmp.io/profiles/image" }]
  , "edit-form"    : [ { "href" : "http://api.pmp.io/docs-validator", "type" :   "application/json"}]
  }  
, "error" : {OBJECT}
}

Image Profile's Fields

  • enclosure/meta's sub-fields :
    • crop : semantic name of the image crop type (e.g. 'medium', 'large' etc.)
    • width : width in pixels
    • height : height in pixels
    • resolution : resolution of the image in ppi (pixels per inch).

Sample Image Document

{
  "version" : "1.0"
, "attributes" : {
    "title"         : "Some Amazing Photo"
  , "guid"          : "c7d6cd84-6b28-4ea2-ae82-a7435bea6679"
  , "published"     : "2013-02-11T13:21:31.598Z"
  , "valid"         : { "from" : "2013-02-11T13:21:31.598Z"
                      , "to"   : "2013-05-11T13:21:31.598Z"}
  , "description"   : "Some caption describing"
  }
, "links" : {
            "profile"      : [ { "href" : "http://api.pmp.io/profiles/image"
                               , "type" : "application/vnd.pmp.collection.doc+json" }]
          , "self"         : [ {"href" : "http://api.pmp.io/docs/c7d6cd84-6b28-4ea2-ae82-a7435bea6679"}]
          , "copyright"    : [ {"href" : "http://npr.org", "title": "Copyright (C) NPR, 2012." }]
          , "author"       : [ {"href" : "http://api.pmp.io/docs/c7d6cd84-6b28-4ea2-ae82-a7435bea6679", "title": "Claire O'Neill" }]
          , "distributor"  : [ {"href" : "http://api.pmp.io/docs/d99273a21-10ac-43d3-83c5-5333b0259e17", "title": "Getty"}]
          , "enclosure"    : [ {"href" : "http://media.npr.org/someiage.png",  "type": "image/png", "meta": { "crop"   : "primary", 
                                                                                                            , "height" : 500
                                                                                                            , "width"  : 700}}
                             , {"href" : "http://media.npr.org/someiage.png",  "type": "image/png", "meta": {"crop": "small"}}
                             , {"href" : "http://media.npr.org/someiage2.png", "type": "image/png", "meta": {"crop": "medium"}}
                             , {"href" : "http://media.npr.org/someiage3.png", "type": "image/png", "meta": {"crop": "large"}}]
          , "alternate"    : [ {"href" : "http://api.pmp.io/docs/ef61593e-f1f9-4400-a321-c301cf7e13fe", "hreflang": "fr", "type": "application/vnd.pmp.collection.doc+json"}
                             , {"href" : "http://api.pmp.io/docs/ef07f2e6-5f78-4c52-9678-17f41fcc25e1", "hreflang": "es", "type": "application/vnd.pmp.collection.doc+json"}]
          , "queries"      : [ {"href" : "http://api.pmp.io/docs/images/queries",   "type": "application/vnd.pmp.query+json"}
                             , {"href" : "http://api.pmp.io/docs/queries",          "type": "application/vnd.pmp.query+json"}]
          , "edit-form"    : [ {"href" : "http://api.pmp.io/docs-validator",        "type" :   "application/json"}]
          }
  
, "error" : {OBJECT}
}

Required Minimum

{
  "version" : "1.0"
, "attributes" : {
    "title" : "Some Title"
  , "guid" : "c7d6cd84-6b28-4ea2-ae82-a7435bea6679"
  , "published" : "2013-02-11T13:21:31.598Z"
  }
, "links" : {
            "profile"      : [ { "href" : "http://api.pmp.io/profiles/image"
                               , "type" : "application/vnd.pmp.collection.doc+json" }]
          , "self"         : [ {"href" : "http://api.pmp.io/docs/c7d6cd84-6b28-4ea2-ae82-a7435bea6679"}]
          , "distributor"  : [ {"href" : "http://api.pmp.io/docs/d99273a21-10ac-43d3-83c5-5333b0259e17", "title": "Getty"}]
          , "enclosure"    : [ {"href" : "http://media.npr.org/someiage2.png", "type" : "image/png"]
          , "edit-form"    : [ {"href" : "http://api.pmp.io/docs-validator",   "type" :   "application/json"}]
          }
  
, "error" : {OBJECT}
}