Stupeflix 1.0 API
This is the Stupeflix 1.0 API description. Other available APIs can be found on the XML Formats Page
The service name is “stupeflix-1.0”.
The xml schema for this xml language can be found here : XML Schema for the slideshow-1.0 API.
To get started immediately, check code samples in the Developer Kit.
Example files
Let's start with an example of a very simple but yet valid movie definition :
<movie service="slideshow-1.0"> <body> <image filename = "http://www.stupeflix.com/m/code/images/Ha_long_bay.jpg"/> <image filename = "http://www.stupeflix.com/m/code/images/Canyon_de_Chelly_Navajo.jpg"/> <image filename = "http://www.stupeflix.com/m/code/images/Monument_Valley_2.jpg"/> </body> </movie>
Alternatively, you can choose to pack all the assets and movie definition in a single file.
<movie service="slideshow-1.0"> <body> <image filename = "Ha_long_bay.jpg"/> <image filename = "Canyon_de_Chelly_Navajo.jpg"/> <image filename = "Monument_Valley_2.jpg"/> </body> </movie>
The zip file that should be uploaded in that case contains :
movie.xml images Ha_long_bay.jpg Canyon_de_Chelly_Navajo.jpg Monument_Valley_2.jpg
In both cases, it will produce a movie with the default kenburns effect, each image being displayed 5 seconds, and with a cross fade transition between images.
In the following examples, we will use short filenames, as if we were uploading a zip file, but you can always use a url for the “filename” attribute.
(Here is the list of supported url protocols )
Let's see now what can be added to this basic example.
Reminder
The generic format for a Stupeflix movie xml file is :
<?xml version="1.0" encoding="UTF-8" ?> <movie service="THE-CHOSEN-SERVICE" > <default> ... </default> <body> ... </body> </movie>
Every duration is in seconds.
Simple Slideshow specifics
You can specify a default transition in the default section. This is optional : if not present, the default transition will be a crossfade of 1 second.
You can specify default parameters for image, such as direction and duration. Example of default definition (these are in fact the “default default” parameters)
<default> <transition type="crossfade" duration = "1.0"/> <image duration="10.0" effect="kenburns" direction="positive"/> </default>
See below for definition of images and transition parameters.
Movie definition
The body section is a sequence of images.
Each image may contain a transition, which will be performed between the current image and the next one. If the last image contains a transition, it is ignored. If no transition is specified, the default one will be used.
The sequence must contain at least one image.
There is at most one soundtrack specified for the movie.
If the movie is shorter than the soundtrack, the soundtrack will be faded out at the end of the movie.
Images
Image attributes are :
- filename : required : the filename in the zip images directory or a url
- duration : optional : default is 10s, unless specified in the default section
- effect : optional : default is “kenburns”
- effect specific parameters
So an image entry example is:
<image filename="lena.jpg" duration="10.0" effect="kenburns" direction="positive"/>
The same result can be obtained with standard defaults using :
<image filename="lena.jpg" />
Depending on the chosen effect, additional attributes may be added.
Effects
Effect attributes are effect specific.
Here is a list of available effects.
Kenburns
Attribute name for the image tag: “kenburns”.
This is the well known Ken Burns Effect.
If the image has roughly the same aspect ratio as the full screen, a zoom in/out effect is done, respectively when direction is positive / negative.
If the image has an horizontal format, a left to right pan is performed if direction is positive (negative of course gives a right to left pan).
Finally, if the image has a vertical format, a bottom to top pan is performed if direction is positive (negative gives a top to botton pan).
Attributes added to the image tag :
- direction : optional : positive / negative : default is positive, unless specified in the default section
Example of an image with an added kenburns effect :
<image filename="lena.jpg" duration="10.0" effect="kenburns" direction="negative" />
Flower
Example of an image with an added flower effect :
<image filename="lena.jpg" duration="10.0" effect="flower"/>
Panel
Example of an image with an added panel effect :
<image filename="lena.jpg" duration="10.0" effect="panel"/>
Explode
Example of an image with an added explode effect :
<image filename="lena.jpg" duration="10.0" effect="explode"/>
Transitions
Here is the page about Transitions.
Soundtrack
The soundtrack is an optional element.
Its attribute are :
- filename
- startTime : optional
Example soundtrack definition :
<soundtrack filename="mymusic.mp3" startTime="4.0"/>
Overlay
The overlay is an optional element.
It will be displayed full screen, on top on all other elements. Transparent parts of the image won't be visible (and so background will be shown).
Its attributes are :
- filename
Example of overlay definition:
<overlay filename="overlay.png"/>
Final example
Let's finish with a complex example, to exemplify the featured options :
<?xml version="1.0" encoding="UTF-8" ?>
<movie service="slideshow-1.0">
<default>
<!-- Let's setup default image, effect and transition parameters -->
<image effect="kenburns" duration="15.0"/>
<transition type="crossfade" duration="2.5">
</default>
<body>
<!-- Let's begin with some video wide information-->
<logo filename="mybrand.jpg" />
<soundtrack filename="mymusic.mp3" startTime="4.0"/>
<!-- Now start the video definition itself -->
<!-- Override the defaults for duration and effect -->
<image filename = "lena.png" duration="4.0" effect="kenburns" direction="negative">
<!-- Override the default transition -->
<transition type="crossfade" duration="0.5"/>
</image>
<!-- Use the defaults for duration and effect-->
<image filename = "blue.jpg" >
<transition type="crossfade" duration="1.5"/>
</image>
<image filename = "landscape.jpg"/>
<!-- Use the default transition -->
<image filename = "mybirthday.jpg"/>
</body>
</movie>