unity-scopes-api

Merge lp:~stolowski/unity-scopes-api/inline-playback-doc into lp:unity-scopes-api/devel

inline-playback-doc
Merge into devel

Proposed by Paweł Stołowski on 2016-03-04

Status:

Merged

Approved by:

Marcus Tomlinson on 2016-03-08

Approved revision:

666

Merged at revision:

663

Proposed branch:

lp:~stolowski/unity-scopes-api/inline-playback-doc

Merge into:

lp:unity-scopes-api/devel

Diff against target:

94 lines (+67/-0)

2 files modified

doc/tutorial.dox (+64/-0)
src/scopes/CategoryRenderer.cpp (+3/-0)

To merge this branch:

bzr merge lp:~stolowski/unity-scopes-api/inline-playback-doc

High

In Progress

Link a bug report

Reviewer	Review Type	Date Requested	Status
Marcus Tomlinson (community)		2016-03-04	Approve on 2016-03-08
PS Jenkins bot (community)	continuous-integration		Approve on 2016-03-08
Review via email: mp+288123@code.launchpad.net

Commit message

Documentation for inline playback and concierge mode.

Description of the change

Documentation for inline playback and concierge mode.

Revision history for this message

Marcus Tomlinson (marcustomlinson) wrote on 2016-03-04:

Looks good! Thanks! Just one spelling mistake.

review: Needs Fixing

lp:~stolowski/unity-scopes-api/inline-playback-doc updated on 2016-03-04

663. By Paweł Stołowski on 2016-03-04: Fix spelling

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2016-03-04:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-scopes-api-devel-ci/1650/rebuild

review: Approve (continuous-integration)

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2016-03-04:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-scopes-api-devel-ci/1651/rebuild

review: Approve (continuous-integration)

Revision history for this message

Marcus Tomlinson (marcustomlinson) wrote on 2016-03-05:

Just a reminder here to update the docs in CategoryRenderer.cpp as well :) Thanks Pawel

review: Needs Fixing

lp:~stolowski/unity-scopes-api/inline-playback-doc updated on 2016-03-08

664. By Paweł Stołowski on 2016-03-08: Added CategoryRenderer doc

Revision history for this message

PS Jenkins bot (ps-jenkins) wrote on 2016-03-08:

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-scopes-api-devel-ci/1653/rebuild

review: Approve (continuous-integration)

Revision history for this message

Marcus Tomlinson (marcustomlinson) wrote on 2016-03-08:

Awesome thanks! 3 small things:

You've added the "Inline music playback" section under the "Case 2: An aggregating scope" section of the tutorial. Could you move it to "Case 1: A simple (non-aggregating) scope".

Could you change:

"e.g. songs from same album; they will be played in the background when the main..."

to:

"e.g. songs from same album; they will be played in sequence when the main..."

I get what you're trying to say, but "in the background" almost implies that they'll all be played on top of each other at the same time.

Also later:

"(an array of uris of additional songs to be played in the background)"

to:

"(an array of uris of additional songs to be played in sequence when the main song finishes)"

review: Needs Fixing

lp:~stolowski/unity-scopes-api/inline-playback-doc updated on 2016-03-08

665. By Paweł Stołowski on 2016-03-08: Doc fixes
666. By Paweł Stołowski on 2016-03-08: -the

Revision history for this message

Marcus Tomlinson (marcustomlinson) wrote on 2016-03-08:

Looks good

review: Approve

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk

Subscribers

People subscribed via source and target branches

to all changes:

Paweł Stołowski

Unity Team

 === modified file 'doc/tutorial.dox'
 --- doc/tutorial.dox	2015-12-10 11:14:24 +0000
 +++ doc/tutorial.dox	2016-03-08 10:11:38 +0000
@@ -657,6 +657,70 @@
+ }
  \endcode
++\paragraph inlineplayback Inline music playback
++
++Results which represent music (songs, albums etc.) can contain an extra data about audio content and can then be played directly from the Dash.
++Such results have a "play" button overlaid on them. To create results that support this functionality two conditions must be met:
++<ul>
++<li>Category renderer definition must contain the "quick-preview-type" key with the value of "audio" in the "template" section;
++<li>Results in the respective category must contain a "quick-preview-data" attribute, each of them is a dictionary with the extra playback data described
++below.
++</ul>
++
++The data assigned to "quick-preview-data" attribute of a Result needs to contain the following keys:
++<ul>
++<li>uri - a playable uri of a media file (path of a local file, or http uri).
++<li>duration - the duration of the media file, in seconds.
++<li>playlist - an array of uris of additional songs, e.g. songs from same album; they will be played in sequence when the main
++song denoted by 'uri' finishes.
++</ul>
++
++Here is an example of a category renderer for inline playback, which uses component mapping to map quick-preview-data to audio-data attribute of a result:
++\code{.cpp}
++static const char CATEGORY_RENDERER[] = R"(
++{
++  "schema-version": 1,
++  "template": {
++    "category-layout": "grid",
++    "card-size": "large",
++    "card-layout" : "horizontal",
++    "quick-preview-type" : "audio"
++  },
++  "components": {
++    "title": "title",
++    "art": {
++      "field": "art"
++    },
++    "subtitle": "artist",
++    "quick-preview-data": {
++        "field": "audio-data"
++    }
++  }
++}
++)";
++\endcode
++
++A sample code that creates a result card representing a song and all songs from same album in a background playlist may look this way:
++\code{.cpp}
++
++CategorisedResult res(category);
++res.set_uri(uri);
++res.set_title(media.getTitle());
++...
++
++VariantMap inline_playback_data;
++inline_playback_data["uri"] = uri;
++inline_playback_data["duration"] = song_duration_in_seconds;
++VariantArray playlist;
++for (const std::string& song: album_songs)
++{
++    playlist.push_back(Variant(song.getUri()));
++}
++inline_playback_data["playlist"] = playlist;
++res["audio-data"] = inline_playback_data;
++
++\endcode
++
  \subsubsection aggscope Case 2: An aggregating scope
  Aggregating scopes are scopes that collect results from other scopes and possibly consolidate, modify, or re-categorise
 === modified file 'src/scopes/CategoryRenderer.cpp'
 --- src/scopes/CategoryRenderer.cpp	2016-01-18 17:50:16 +0000
 +++ src/scopes/CategoryRenderer.cpp	2016-03-08 10:11:38 +0000
@@ -69,6 +69,7 @@
  \arg \c collapsed-rows Number of result rows displayed while the category is collapsed; possible values: any non-negative integer, where 0 fully expands the category (only affects grid and vertical journal)
  \arg \c card-background Background color for the cards; string; URI in the format \verbatim color:///#rrggbb \endverbatim or \verbatim color:///color_name
  \endverbatim or \verbatim gradient:///#rrggbb/#rrggbb \endverbatim or an image URI (will be stretched)
++\arg \c quick-preview-type The type of media content represented by result cards, for use with inline playback; the only currently supported type is "audio".
  \subsection components1 components keys
@@ -83,6 +84,8 @@
  \arg \c background Card background URI, can override the default specified in the card-background field of the template section (same format as for card-background)
  \arg \c attributes Array of dictionaries specifying text and an optional icon (keys: "value", "icon")
  \arg \c overlay-color Color of overlay for templates with overlay
++\arg \c quick-preview-data A dictionary with the following keys: \c "uri" (an uri of audio stream or file), \c "duration" (duration in seconds), \c "playlist"
++(an array of uris of additional songs to be played in sequence when the main song finishes).
  \section example Example