Skip to content
GitLab
Commit 6a39d7d4 authored by Matthias Klumpp's avatar Matthias Klumpp
Browse files

spec: Specify videos as a screenshot option 

See #175 for the discussion about this feature.
parent 6ed447da
Hide whitespace changes
Inline Side-by-side
docs/sources/collection/xmldata.xml
View file @ 6a39d7d4
......@@ -41,7 +41,7 @@
<code>&lt;component&gt;</code> tags of different <literal>type</literal>s as children.
</para>
<para>
Data to fill the different component elements is usually taken from their <ulink url="http://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop files</ulink>
Data to fill the different component elements is usually taken from their <ulink url="https://standards.freedesktop.org/desktop-entry-spec/latest/">Desktop files</ulink>
and package data. However, if an upstream project ships metainfo files (see <xref linkend="chap-Metadata"/>),
values defined there should override data from any other source.
</para>
......@@ -159,7 +159,7 @@
</para>
<para>
In case of a component of type <literal>desktop-application</literal>, the application name as defined in the application's
<ulink url="http://standards.freedesktop.org/desktop-entry-spec/latest/">desktop file</ulink> is used.
<ulink url="https://standards.freedesktop.org/desktop-entry-spec/latest/">desktop file</ulink> is used.
</para>
</listitem>
</varlistentry>
......@@ -171,7 +171,7 @@
The <code>&lt;project_license/&gt;</code> tag is indicating the license of the component.
It should be a <ulink url="https://spdx.org/specifications">SPDX license expression</ulink>.
A full list of recognized licenses and their identifiers can be found at the
<ulink url="http://spdx.org/licenses/">SPDX OpenSource License Registry</ulink>.
<ulink url="https://spdx.org/licenses/">SPDX OpenSource License Registry</ulink>.
</para>
<para>
You can find more information about this tag at the metainfo description for <xref linkend="tag-project_license"/>.
......@@ -287,7 +287,7 @@
</para>
<programlisting language="XML"><![CDATA[<icon type="stock">gimp</icon>
<icon type="cached">firefox.png</icon>
<icon type="remote" width="64" height="64">http://example.com/icons/foobar.png</icon>
<icon type="remote" width="64" height="64">https://example.com/icons/foobar.png</icon>
<icon type="local" width="64" height="64">/usr/share/pixmaps/foobar.png</icon>]]></programlisting>
<para>
Multiple <code><![CDATA[<icon/>]]></code> tags might be combined for one application, for example to define a <literal>stock</literal> icon
......@@ -325,7 +325,7 @@
This tag can contain one or more <code><![CDATA[<category>]]></code> tags, describing the categories this component
is located in. This tag is usually applied to components of type <literal>desktop-application</literal>, although it might be used by others later.
This data is usually taken from Desktop files, a list of categories can be found in the
<ulink url="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop menu spec</ulink>.
<ulink url="https://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop menu spec</ulink>.
Example:
</para>
<programlisting language="XML"><![CDATA[<categories>
......@@ -378,10 +378,10 @@
<para>
The <literal>screenshots</literal> tag is described for metainfo files in <xref linkend="tag-screenshots"/>. In collection metadata, the tag
has the exact same format as in metainfo files.
The metadata generator may add an arbitrary number of resized thumbnails though.
The metadata generator may add an arbitrary number of resized thumbnails for <literal>image</literal> type screenshots though.
</para>
<para>
Every <code><![CDATA[<screenshot>]]></code> is defined by several images of different sizes.
Every static-image <code><![CDATA[<screenshot>]]></code> is defined by several images of different sizes.
All images should have their width and hight set as arguments. Also, one of the images should be marked as <code>type="source"</code>,
indicating that it is the unscaled version of the screenshot.
Images of <code>type="thumbnail"</code> define thumbnails of the screenshot.
......@@ -408,16 +408,24 @@
on the image shown. The tag is translatable.
</para>
<para>
Every image should have a full remote url set, usually pointing to a cache of images maintained by the repository vendor.
For <code><![CDATA[<screenshot>]]></code> tags that contain <literal>video</literal> elements, a collection metadata generator may impose any restrictions to them,
including completely removing them from the output, imposing filesize limits, etc.
Upstream metainfo files should not rely on the videos being present and must always have a static screenhot for the software component as well.
</para>
<para>
Every image or video should have a full remote url set, usually pointing to a cache of images maintained by the repository vendor.
Example:
</para>
<programlisting language="XML"><![CDATA[<screenshots>
<screenshot type="default">
<caption>FooBar showing kitchen-sink functionality.</caption>
<caption xml:lang="de">FooBar beim Ausführen der Spühlbecken-Funktion.</caption>
<image type="source" width="800" height="600">http://www.example.org/en_US/main.png</image>
<image type="thumbnail" width="752" height="423">http://www.example.org/en_US/main-large.png</image>
<image type="thumbnail" width="112" height="63">http://www.example.org/en_US/main-small.png</image>
<image type="source" width="800" height="600">https://www.example.org/en_US/main.png</image>
<image type="thumbnail" width="752" height="423">https://www.example.org/en_US/main-large.png</image>
<image type="thumbnail" width="112" height="63">https://www.example.org/en_US/main-small.png</image>
</screenshot>
<screenshot>
<video container="mkv" codec="av1" width="800" height="600">https://www.example.org/en_US/screencast.mkv</video>
</screenshot>
<screenshot>
....
......@@ -443,7 +451,7 @@
The distributor decides which components should be made compulsory, however it is generally a good idea to follow upstream's recommendations on that matter.
</para>
<para>
A list of all allowed values for this tag is defined in the <ulink url="http://standards.freedesktop.org/menu-spec/latest/apb.html">XDG Menu Specification</ulink>.
A list of all allowed values for this tag is defined in the <ulink url="https://standards.freedesktop.org/menu-spec/latest/apb.html">XDG Menu Specification</ulink>.
Software center applications will only recognize these values.
</para>
</listitem>
......@@ -566,10 +574,10 @@
The <literal>type</literal> property of this tag indicates which 3rd-party software installation solution the bundle belongs to.
Currently supported solutions are:
<itemizedlist>
<listitem><para>The <ulink url="http://people.freedesktop.org/~mak/limba/">Limba Project</ulink>, using the value <code>limba</code>.</para></listitem>
<listitem><para><ulink url="http://flatpak.org/">Flatpak</ulink> bundles, using the value <code>flatpak</code>.</para></listitem>
<listitem><para><ulink url="http://appimage.org/">AppImageKit</ulink> bundles, using the value <code>appimage</code>.</para></listitem>
<listitem><para><ulink url="http://snapcraft.io/">Snappy</ulink> snap bundles, using the value <code>snap</code>.</para></listitem>
<listitem><para>The <ulink url="https://people.freedesktop.org/~mak/limba/">Limba Project</ulink>, using the value <code>limba</code>.</para></listitem>
<listitem><para><ulink url="https://flatpak.org/">Flatpak</ulink> bundles, using the value <code>flatpak</code>.</para></listitem>
<listitem><para><ulink url="https://appimage.org/">AppImageKit</ulink> bundles, using the value <code>appimage</code>.</para></listitem>
<listitem><para><ulink url="https://snapcraft.io/">Snappy</ulink> snap bundles, using the value <code>snap</code>.</para></listitem>
<listitem><para>Plain and possibly compressed tarballs, using the value <code>tarball</code>.</para></listitem>
</itemizedlist>
</para>
......@@ -666,11 +674,11 @@
<mimetype>x-scheme-handler/http</mimetype>
<mimetype>x-scheme-handler/https</mimetype>
</mimetypes>
<url type="homepage">http://www.mozilla.com</url>
<url type="homepage">https://www.mozilla.com</url>
<screenshots>
<screenshot type="default">
<image type="source" width="800" height="600">http://www.awesomedistro.example.org/en_US/firefox.desktop/main.png</image>
<image type="thumbnail" width="200" height="150">http://www.awesomedistro.example.org/en_US/firefox.desktop/main-small.png</image>
<image type="source" width="800" height="600">https://www.awesomedistro.example.org/en_US/firefox.desktop/main.png</image>
<image type="thumbnail" width="200" height="150">https://www.awesomedistro.example.org/en_US/firefox.desktop/main-small.png</image>
</screenshot>
</screenshots>
<provides>
......@@ -681,7 +689,7 @@
<id>org.freedesktop.PulseAudio</id>
<name>PulseAudio</name>
<summary>The PulseAudio sound server</summary>
<url type="homepage">http://www.freedesktop.org/wiki/Software/PulseAudio/</url>
<url type="homepage">https://www.freedesktop.org/wiki/Software/PulseAudio/</url>
<project_license>GPL-2.0+</project_license>
<provides>
<library>libpulse-simple.so.0</library>
......
docs/sources/collection/yamldata.xml
View file @ 6a39d7d4
......@@ -279,9 +279,9 @@
Example:
</para>
<programlisting><![CDATA[Url:
homepage: http://example.org
faq: http://example.org/faq
bugtracker: http://bugs.example.org/report-issue]]></programlisting>
homepage: https://example.org
faq: https://example.org/faq
bugtracker: https://bugs.example.org/report-issue]]></programlisting>
<literallayout>Field info: <property>value-type</property>:<emphasis>dict</emphasis></literallayout>
</listitem>
......@@ -427,7 +427,8 @@
<term>source-image</term>
<listitem>
<para>
Describes the source image for this screenshot. It has the following keys:
Describes the source image for this screenshot. If this field is present, <literal>source-video</literal> must not be present as well.
The field valus is a dictionary with the following keys:
</para>
<itemizedlist>
<listitem>
......@@ -453,7 +454,7 @@
</para>
</listitem>
</itemizedlist>
<literallayout>Field info: <property>value-type</property>:<emphasis>dict</emphasis>, <property>required</property>:<emphasis>yes</emphasis></literallayout>
<literallayout>Field info: <property>value-type</property>:<emphasis>dict</emphasis>, <property>required</property>:<emphasis>conditional</emphasis></literallayout>
</listitem>
</varlistentry>
......@@ -463,11 +464,55 @@
<para>
A list of an arbitrary number of screenshots. All screenshots are of type <emphasis>dict</emphasis> and must contain the same keys as described for
<literal>source-image</literal>.
This key must not be present if <literal>source-video</literal> is present.
</para>
<literallayout>Field info: <property>value-type</property>:<emphasis>list</emphasis>, <property>required</property>:<emphasis>no</emphasis></literallayout>
</listitem>
</varlistentry>
<varlistentry>
<term>source-video</term>
<listitem>
<para>
Describes the video for this screenshot. If this field is present, <literal>source-image</literal> must not be present as well.
The field valus is a dictionary with the following keys:
</para>
<itemizedlist>
<listitem>
<para><literal>container</literal></para>
<para>The video container format (string, as described in the XML specification)</para>
</listitem>
<listitem>
<para><literal>codec</literal></para>
<para>The video codec format (string, as described in the XML specification)</para>
</listitem>
<listitem>
<para><literal>height</literal></para>
<para>The video height (<property>value-type</property>:<emphasis>int</emphasis>)</para>
</listitem>
<listitem>
<para><literal>width</literal></para>
<para>The video width (<property>value-type</property>:<emphasis>int</emphasis>)</para>
</listitem>
<listitem>
<para><literal>url</literal></para>
<para>
The full video url, or the url component added to <literal>MediaBaseUrl</literal>,
if defined (<property>value-type</property>:<emphasis>str</emphasis>).
</para>
</listitem>
<listitem>
<para><literal>lang</literal></para>
<para>
The language this screenshot video is translated in. The value is a locale string.
(<property>value-type</property>:<emphasis>str</emphasis>, <property>required</property>:<emphasis>no</emphasis>)
</para>
</listitem>
</itemizedlist>
<literallayout>Field info: <property>value-type</property>:<emphasis>dict</emphasis>, <property>required</property>:<emphasis>conditional</emphasis></literallayout>
</listitem>
</varlistentry>
<varlistentry>
<term>caption</term>
<listitem>
......@@ -489,15 +534,21 @@
si: Foobar shoeewing kischän-sünk funzionality
source-image:
height: 800
url: http://www.example.org/en_US/main.png
url: https://www.example.org/en_US/main.png
width: 600
thumbnails:
- height: 423
width: 752
url: http://www.example.org/en_US/main-large.png
url: https://www.example.org/en_US/main-large.png
- height: 63
width: 112
url: http://www.example.org/en_US/main-small.png]]></programlisting>
url: https://www.example.org/en_US/main-small.png
- source-video:
container: mkv
codec: av1
height: 900
url: https://www.example.org/en_US/screencast.mkv
width: 1600]]></programlisting>
<literallayout>Field info: <property>value-type</property>:<emphasis>list</emphasis></literallayout>
</listitem>
......@@ -868,7 +919,7 @@ Requires:
File: DEP-11
Version: '0.8'
Origin: chromodoris-main
MediaBaseUrl: http://metadata.tanglu.org/appstream/media/
MediaBaseUrl: https://metadata.tanglu.org/appstream/media/
---
Type: desktop-application
ID: gconf-editor.desktop
......@@ -945,7 +996,7 @@ Keywords:
- bibtex
ProjectLicense: GPL-2.0
Url:
homepage: http://texstudio.sourceforge.net/
homepage: https://texstudio.sourceforge.net/
Categories:
- Office
- Publishing
......
docs/sources/metainfo/component.xml
View file @ 6a39d7d4
......@@ -849,14 +849,20 @@
<listitem>
<para>
Visual components (like fonts or graphical applications) may choose to add one or multiple screenshots to their metadata.
Screenshots can be either a video or a static image.
</para>
<para>
The <code>&lt;screenshots/&gt;</code> tag contains multiple <code>&lt;screenshot/&gt;</code> children, where at least one of them must have the property
<code>type="default"</code> to indicate the primary screenshot of the software. Every <code>&lt;screenshot/&gt;</code> tag must have at least
one <code>&lt;image/&gt;</code> child.
one <code>&lt;image/&gt;</code> or <code>&lt;video/&gt;</code> child, but never an <literal>image</literal> and <literal>video</literal> at the same time.
Also, screenshots containing videos must not be the default screenshot.
</para>
<para>
The value of the <code>&lt;image/&gt;</code> tag is a direct HTTP/HTTPS URL to a screenshot uploaded to a public location on the web.
Images should also be in be in PNG or JPEG format. PNG is the preferred format; JPEG should only be used when screenshots include large photographs or other
images where a lossy format like JPEG may compress better.
</para>
<para>
The value of the <code>&lt;image/&gt;</code> tag is a direct HTTP/HTTPS/FTP URL to a screenshot uploaded to a public location on the web.
The <code>&lt;image/&gt;</code> tag may have the following properties:
<itemizedlist>
<listitem>
......@@ -887,14 +893,57 @@
</listitem>
</itemizedlist>
</para>
<para>
The value of the <code>&lt;video/&gt;</code> tag is a direct HTTP/HTTPS URL to a video uploaded to a public location on the web. The video must be in a
<ulink url="https://www.matroska.org/">Matroska (.mkv)</ulink> or <ulink url="https://www.webmproject.org/">WebM</ulink> container and use either the
<ulink url="https://www.webmproject.org/vp9/">VP9</ulink> or <ulink url="http://aomedia.org/av1-features/">AV1</ulink> codec.
The video should ideally work without any audio, but if audio is needed, the <ulink url="https://opus-codec.org/">Opus</ulink> codec should be used.
Software centers may still play the video without any sound though. Additionally, AppStream metadata repositories (like in distributions such as Fedora and Debian)
may impose size limitations to video files delivered by their CDN, so it is recommended to keep the video file size below 10MiB.
There is also a chance that software centers do not display any video at all, so a video must never be in a default screenshot.
</para>
<para>
The <code>&lt;video/&gt;</code> tag may have the following properties:
<itemizedlist>
<listitem>
<para><code>container</code></para>
<para>
The video container used, can be <code>webm</code> or <code>mkv</code>.
</para>
</listitem>
<listitem>
<para><code>codec</code></para>
<para>
The video codec used, can be <code>av1</code> or <code>vp9</code>.
</para>
</listitem>
<listitem>
<para><code>width</code></para>
<para>
The width of the video in pixels.
</para>
</listitem>
<listitem>
<para><code>height</code></para>
<para>
The height of the video in pixels.
</para>
</listitem>
<listitem>
<para><code>xml:lang</code></para>
<para>
The language this video is translated in. This property should only be present if there are multiple videos with
different locales present.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Optionally, a <code>&lt;screenshot/&gt;</code> tag may have a translatable <code>&lt;caption/&gt;</code> child, defining a short (ideally not more than 256 characters)
description of what the user can see on the referenced screenshot.
</para>
<para>
Ideally, all screenshots should have a 16:9 aspect ratio, and should have a width that is no smaller than 620 pixels.
They should also be in be in PNG or JPEG format. PNG is the preferred format; JPEG should only be used when screenshots include large photographs or other
images where a lossy format like JPEG may compress better.
Ideally, all image screenshots as well as videos should have a 16:9 aspect ratio, and should have a width that is no smaller than 620 pixels.
</para>
<para>
Example:
......@@ -908,6 +957,9 @@
<caption>Foobar showing the frobnicate functionality.</caption>
<image type="source" width="1600" height="900">https://example.com/foobar/screenshot-2.png</image>
</screenshot>
<screenshot>
<video codec="av1" width="1600" height="900">https://example.com/foobar/screencast.mkv</video>
</screenshot>
</screenshots>]]></programlisting>
</listitem>
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment