Playlist Reference Guide

The playlist is a Science On a Sphere construct for organizing and grouping together content for a presentation. Playlists are analogous to a playlist on an MP4 player. Playlists are simple text files and are read and interpreted by the main SOS application interface.

Attribute/Value Pairs

animate

 = 0 or 1 
If 0, then don't immediately start animating when the dataset is loaded (i.e. you must hit play). Otherwise, automatically animate when the dataset gets loaded. In auto presentation mode, the dataset will always animate automatically, even if animate = 0.

audio

 = /path/to/audio/file
The audio file can be any of the following formats: .mp3, .wav, .ogg, .aif, and .mp4. Audio only loops when the duration attribute is set.

background

 = Deprecated attribute since SOS v4.0
Replaced by layer attributes.

caption

 = /path/to/file.srt
An industry standard SubRip Subtitle file (.srt) that contains a sequential set of closed captions/subtitles with their start and end timecodes and that runs in sync with global data that is either a movie or a directory of images.  The caption will be displayed four times simultaneously around the sphere.
(New in SOS v5.4)

captionformat

 = /path/to/captionformat.html
The format of the caption text (i.e. font, color of text, color of background, etc.) is written as an SOS-specific html file. By default, the name of the formatting file for captions is captionformat.html.  This file should typically only be auto-created and/or accessed by the SOS Visual Playlist Editor.  If no captionformat file is specified, the captions text will be rendered in white color against a semi-transparent black background, and will use the Free Sans font.
(New in SOS v5.4)

captionheight

 = value in degrees
The height in positive degrees of latitude.  (Note that the width of the caption is automatically computed.)
(New in SOS v5.4)

captionhorizontal

 = value in degrees longitude
The horizontal position in degrees of the caption center. A positive value is specified as east of the center of each projector. The default value is 0 degrees and the value can range from -180 to 180.
(New in SOS v5.4)

captionvertical

 = value in degrees latitude
The vertical position in degrees of the caption center. A positive value is specified as north of the center of each projector.  The default value is -25 degrees and the value can range from -90 to 90.
(New in SOS v5.4)

captionvisible

 = true or false
The initial visibility of the caption when loaded.  The default value is false.
(New in SOS v5.4)

catalog_url

 = url_of_dataset 
The SOS Data Catalog url that corresponds to the dataset. On the iPhone/iPad, when a new dataset in the Playlist is selected, the web page for this dataset will automatically be loaded in the Web Page tab. If the url cannot be found, the SOS Data Catalog home page will be displayed by default.
(New in SOS v4.0)

category

 = Deprecated attribute since SOS v4.3
Replaced by the majorcategory attribute in all dataset playlists.  Retained in all NOAA-managed playlists for backward compatibility, but it is only used in SOS software (v4.3+) as a fallback value when the majorcategory attribute is missing.  

creator

 = name of the creator of dataset 
The name of the person or organization who created this dataset.  Removed from all NOAA-managed dataset playlists in SOS v4.3 and now used only for dataset playlists placed in the /shared/sos/media/site-custom folder.  

data

 = /path/to/data (must specify if not specifying the layerdata attribute)
Specifies the path to an image, video, or directory of images that will be used as the main data displayed on the sphere. (NOTE: WMS URL’s must be prefixed with ‘//WMS//’; see the SOS User Manual for more instructions on WMS URL’s) Acceptable image formats are .jpg, .jpeg, .png, .tiff, .gif, and .bmp; acceptable video format is .mp4. While most of the files are typically local on the computer, you can also point to a URL, such as http://example.com/image.jpg

datadir

 = Deprecated attribute since SOS v3.0
Replaced by the data and layerdata atrributes

description

 = {{ text }} 
Text that describes the dataset, used to supply information in the media library for dataset playlists placed in the /shared/sos/media/site-custom folder.  The text must be enclosed between the special characters "{{" at the beginning and "}}" at the end and may span multiple lines in the playlist file.  Special characters including single and double quotes are allowed as part of the text. If this keyword is missing, by default the SOS software will assign site-custom datasets a description value the same as its name value.  Ignored by SOS software for NOAA-managed playlists. 
(New in SOS v5.0)

duration

 = repeat time in seconds for entire dataset, including PIPs and audio 
The timing of pips is not related to the underlying dataset. The underlying data loops, and dwells may apply to the first and last frame as it loops, but the pip timing is unaffected by that. To make the pips loop as well, set the duration to the desired repeat time, in seconds. The default (and max) duration is 86400 seconds (24 hours).

endframe

 = some frame number 
Trim a long animation. If specified, the animation will only display frames beginning at startframe value (if set) and going through endframe value. Endframe values can be absolute frame numbers, or if they are negative, the frame number is relative to the end of the animation. The value of the endframe can also be specified with the word "end" to specify the end of the animation. The default is the last frame and the max value is 108000. 

firstdwell

 = number in milliseconds
Referred to as "Time to dwell on first frame" in VPLE.
Specifies the time in milliseconds that the animation will stop on the first frame. The default value is 0 milliseconds and the max value is 100,000 milliseconds.

fps

 = frames per second
How quickly the animation sequences through data frames. Minimum value = 0.1 Maximum value = 100000.0 and the default is 30.0. 

framewidth

 = size in pixels of the data or first layerdata image or movie frame in the lateral direction
SOS datasets are always rectangular with a 2:1 size ratio and this value is the larger of the two dimensions.  It is used to indicate the resolution of the dataset, which is used primarily to filter high resolution datasets, i.e., greater than 4096 x 2048.  The default value is 0. 
(New in SOS v4.0)

icons

 = /path/to/filename 
The filename of the annotation icon to make available in the iPad's Icons dialog when this dataset is selected. If specifying more than one icon, the list should be a comma separated list with no spaces.
(New in SOS v4.0)

include

 = /path/to/playlist.sos 
Specifies a path to a dataset’s playlist.sos file The include attribute should only be used in a presentation playlist. A playlist.sos file must contain only a single dataset. Usually included from the data directory where it resides. EX: include = /shared/sos/media/land/blue_marble/blue_marble/playlist.sos

keywords

 = comma separated list of keywords 
Keywords to aid in searching. Removed from all NOAA-managed dataset playlists and used by SOS software (v4.3 and newer) only for dataset playlists placed in the /shared/sos/media/site-custom folder.

kmllegendxoffset

 = degree of longitude offset 
By default KML legends and ancillary graphics are placed at 180 degrees longitude. Use this factor to specify the degree to offset the legends.
(New in SOS v4.1)

kmllegendyoffset

 = degree of latitude offset 
By default KML legends and ancillary graphics are placed at 0 degrees latitude. Use this factor to specify the degree to offset the legends. Positive values move the legends north of the equator.
(New in SOS v4.1)

kmlpipscale

 = scale factor 
What scale factor to apply to all image placemarks in the KML file. If placemarks are small, a factor of 1.5 would increase the size by 50%. The default value is 1.0. 
(New in SOS v4.1)

label

 = default (this will display the filename of each frame) OR /path/to/labels.txt 
If not specified, no labels will show. If a labels.txt file is specified, the label file should contain one line per frame of the animation. This is usually used to specify a label or time stamp for an image frame sequence. Label files are ignored for single texture datasets. The label will be displayed four times simultaneously around the sphere.  If a bad label file is specified, the label will be set to either the name of the image file (if viewing an image frame sequence) or the current frame number (if viewing a movie) that is currently being displayed on SOS.

labelColor

 Deprecated attribute since SOS v5.3: R, G, B, Alpha
The value for each R, G, B, or Alpha parameter must be in the range [0 - 255]. The following symbolic names can also be used: white, black, red, green, blue. The default value is white.

labelformat

 = /path/to/labelformat.html 
The format of the label text (i.e. font, color of text, color of background, etc.), written as an SOS-specific html file. By default, the name of the formatting file for labels is labelformat.html.  This file should typically only be auto-created and/or accessed by the SOS Visual Playlist Editor.  If no labelformat file is specified, the labels text will be rendered in white color against a transparent background, and will use the Free Sans font.
(New in SOS v5.3)

labelheight

 = value in degrees
The height in positive degrees of latitude.  (Note that the width of the label is automatically computed.)
(New in SOS v5.3)

labelhorizontal

 = value in degrees longitude
The horizontal position in degrees of the label center. A positive value is specified as east of the center of each projector. The default value is 0 degrees and the value can range from -180 to 180.
(New in SOS v5.3)

labelposition

 Deprecated attribute since SOS v5.3: default OR x,y (Note no space after the comma.)
The x,y range goes from: [-1,-1] to [1,1]. If no labelposition is specified, the default value of -0.3,-0.5 will be used. The label will still be displayed four times simultaneously around the sphere.

labelvertical

 = value in degrees latitude
The vertical position in degrees of the label center. A positive value is specified as north of the center of each projector.  The default value is -25 degrees and the value can range from -90 to 90.
(New in SOS v5.3)

labelvisible

 = true or false
The initial visibility of the label when loaded.  The default value is true.
(New in SOS v5.3)

lastdwell

 = time in milliseconds 
Specifies the time in milliseconds that the animation will stop on the first and last frame. The default value is 0 milliseconds and the max value is 100,000 milliseconds. 

layer

 = name 
Creates a new layer with the given name, which may contain spaces and continues to the end of the line. 
(New in SOS v4.0)

layeralpha

 = opacity of layer 
The initial alpha value of the layer when loaded. The value can range from 0.0 to 1.0 and the default value is 1.0. 
(New in SOS v4.0)

layerdata

 = /path/to/data 
Specifies the data file that will be loaded into the new layer (NOTE: WMS URL’s must be prefixed with ‘//WMS//’ See the SOS 4.1 WMS Release Notes for more instructions on WMS URL’s.)
(New in SOS v4.0)

layereast

 = value in degrees
The eastern edge longitude in degrees of the layer dataset. Depending on the values specified, the layer may wrap around itself, not cover the whole, or be inverted in some fashion. If you would like a layer to cover the whole sphere, omit the directional layer attributes. The values can range from -180 to 180. The default value is 180. 
(New in SOS v4.0)

layermaxzoom

 = value 
The max zoom value that the layer will appear at when using the magnifying glass. The default and max value is 1,000,000. 
(New in SOS v4.0)

layerminzoom

 = value
The max zoom value that the layer will appear at when using the magnifying glass. The default value is 0 and max value is 1,000,000. 
(New in SOS v4.0)

layernorth

 = value in degrees
The northern edge latitude in degrees of the layer dataset. Depending on the values specified, the layer may wrap around itself, not cover the whole, or be inverted in some fashion. If you would like a layer to cover the whole sphere, omit the directional layer attributes. The values can range from -90 to 90. The default value is 90. 
(New in SOS v4.0)

layersouth

 = value in degrees
The southern edge latitude in degrees of the layer dataset. Depending on the values specified, the layer may wrap around itself, not cover the whole, or be inverted in some fashion. If you would like a layer to cover the whole sphere, omit the directional layer attributes. The values can range from -90 to 90. The default value is -90. 
(New in SOS v4.0)

layervisible

 = true OR false 
The initial visibility of the layer when loaded. The default value is true. 
(New in SOS v4.0)

layerwest

 = value in degrees 
The western edge longitude in degrees of the layer dataset. Depending on the values specified, the layer may wrap around itself, not cover the whole, or be inverted in some fashion. If you would like a layer to cover the whole sphere, omit the directional layer attributes. The values can range from -180 to 180. The default value is 180. 
(New in SOS v4.0)

majorcategory

 = main category of a NOAA-managed dataset
Main categorization of this dataset, used to populate the media library for NOAA-managed dataset playlists.  Should be ignored by SOS software for dataset playlists placed under /shared/sos/media/site-custom, which are all assigned a major category = Site-Custom.
(New in SOS v4.3)

name

 = Dataset name shown on menu (REQUIRED) 
Name or label for the playlist entry. The name is used as text for the list of datasets in the presentation playlist on SOS Stream GUI.

pip

 = /path/to/data 
A pip is an image, video, directory of images, or text pip (SOS-specific html file used to store the text and its attributes such as font size and color) that will appear in a picture-in-a-picture window on the sphere. The appearance of the pip window on the sphere is based on the values set by the other pip control attributes. Multiple pip's may be specified. 

Note that if the pip is a text pip, this file should typically only be auto-created and/or accessed by the SOS Visual Playlist Editor.

Note that video pips only play through one time and will not repeat (see the “duration” attribute for alternate behavior) and that pips with audio have to have audio specified with the audio attribute. 

A pip can also be assigned a url image. For example: pip = http://example.com/image.jpg.  A pip can also be specified as an rtsp stream in order to show a live audio/video stream on the sphere. For example: pip = rtsp://server_name/stream_name.sdp

pipalpha

 = pip opacity 
Opacity of pip over underlying image. Minimum = 0.0 (invisible) Maximum = 1.0 (completely opaque). The default value is 1.0. 

pipcoords

 = lat,lon (No spaces should be put between the comma) 
This defines the position of the pip. This is similar to setting pipvertical and piphorizontal values, but here the pip shape remains constant as it moves up and down. Using the pipvertical attribute, the sides of the pip follow lines of latitude, which distorts the true shape of the pip as it moves up and down. Both approaches can be useful. Note that the image will become more difficult to read or view as it approaches the poles. The default value is 0,0, the minimum value is -90,-180, and the maximum value is 90,180. 

pipdelay

 = time in seconds
The time delay before the pip is displayed. The default value is 0 seconds, and the maximum is 86400 seconds. 

pipfadein

 = time in seconds
Positive length of time pip takes to fade in. The default value is 0 seconds, and the maximum is 86400 seconds. 

pipfadeout

 = time in seconds
Positive length of time pip takes to fade out. The default value is 0 seconds, and the maximum is 86400 seconds. 

pipfps

 = frames per second of pip
The pip playback speed in frames per second for mpeg pips and pips that play a directory of images. A default fps of 30.0 is used unless pipfps is specified. The minimum value is 0.0 seconds and the maximum value = 100000.0 seconds. 

pipheight

 = value in degrees
The height in positive degrees of latitude. To make a pip the height of the sphere, 180 may be specified. Note that part of the image may disappear into the black holes at the poles of the sphere. The aspect ratio of the image or movie will be maintained unless the pipwidth attribute  is also specified. The default value is 40 degrees and the maximum value is 180 degrees. 

piphorizontal

 = value in degrees longitude
The horizontal position in degrees of pip center. For a pipstyle value of projector, a positive value is specified as east of the center of each projector. See the “pipcoords” attribute for additional, relevant information. The default value is 0 and the value can range from -180 to 180. 

pipname

 = name 
The name of the pip. Defaults to the pip filename if not specified. 
(New in SOS v5.2)

pippath

 = /path/to/filename.csv
Each type of PIP can be given a simple path file that contains coordinate locations that indicate how to automatically move the PIP on the sphere as the dataset is animating.  The path file is a simple comma separated value file (.csv file format) that contains a list of increasing frame numbers, each with a latitude and longitude value.  As the dataset is animating, the PIP will be moved to the location specified in the file that corresponds to the current frame being displayed on SOS.
(New in SOS v5.4)

pippathformat

 = /path/to/filename.json
A json formatted file that defines attributes related to a pippath.  For example, attributes include the option to turn path lines ON/OFF, change the color or size of path lines, etc.  This file should typically only be auto-created and/or accessed by the SOS Visual Playlist Editor.
(New in SOS v5.4)

pipstyle

 = projector or globe or room 
Projector is default, where the pip is replicated and placed at a default position in front of each projector. A pipstyle of globe places one pip on the globe, by default with a latitude and longitude of both zero. As the sphere is tilted and rotated, this pip moves with the globe. A pipstyle of room places one pip on the globe, by default with latitude and longitude both zero. As the sphere is tilted and rotated, this pip remains stationary relative to the room, with the sphere data moving underneath it.

piptimer

 = time in seconds
The length of time the pip is displayed, including fadein/fadeout (seconds). The default value is 0, which means a pip image will stay on indefinitely, and a pip video will show the last frame of the video indefinitely. The maximum value is 86400 seconds. 

pipvertical

 = value in degrees 
Vertical position in degrees of pip center above equator. For a pipstyle value of projector, a positive value is specified as north of the center of each projector. See the “pipcoords” keyword for additional, relevant information. The default value is 0 and the value can range from -90 to 90. 

pipvisible

 = true OR false 
The initial visibility of the pip when loaded. The default value is true. 
(New in SOS v5.2)

pipwidth

 = value in degrees longitude
The width in positive degrees of longitude. When specifying a pip width without specifying the “pipheight” keyword, the pip’s image or movie will maintain its aspect ratio. Note that the pip can wrap around the top of the sphere if it is made too wide. The default value is 40 degrees and the maximum value is 360. 

publisher

 = Deprecated attribute since SOS v4.3
Previously used to indicate the name of the person or organization who published this dataset.  Ignored by SOS software (v4.3+) and removed from all NOAA-managed dataset playlists (March 2015).  

rename

 = Dataset name shown on menu 
Name or label for the playlist entry. The name is used as text for the list of datasets in the presentation playlist on SOS Stream GUI.

script

 = filename
Run the specified script (or executable) when the dataset is started. The script will be killed when the system plays the next dataset. This provides a way of coordinating arbitrary additional activities with the dataset. The script may also connect back to the SOS automation control interface to control the system with timing not otherwise achievable via the playlist keywords.

skip

 = n (where n is the skip factor for an animation through image frames (movies and directory of images))
skip = 1 will skip every other image frame in an animation skip = 2 will play every third image frame, etc. As skip gets bigger, the total image frames that are animated goes down. The default value is 0 and the maximum value is 108,000. 

startframe

 = frame number
Trim a long animation. If specified, the animation will only display frames beginning at startframe value and going through endframe value. The default value is 0 and the maximum value is 108,000. 

stopframe

 = frame number 
Stop animating when the animation reaches this frame number. The default value is -1 and the maximum value is 108,000. NOTE: to start animated again after reaching the stopframe, a presenter must advance to the next frame and then press play. 

subcategory

 = subcategory for a site-custom dataset 
Subcategorization of the dataset, used to populate the media library for dataset playlists placed in the /shared/sos/media/site-custom folder.  Only one value is allowed (i.e., not a comma separated list).  If this keyword is missing, the SOS software will assign site-custom datasets a subcategory = Uncategorized.  A subcategory should always be place on a line lower that the name attribute and only be used once per dataset.  Ignored by SOS software for NOAA-managed playlists. In your site-custom dataset folder, if you have a dataset playlist.sos file AND variation dataset playlists, such as playlist_audio.sos, the subcategory keyword is ignored for variation playlists. You must include the subcategory keyword in the playlist.sos file if you want this dataset and its variations to be displayed in a particular Subcategory of the Site-Custom Major Category on the iPad.
(New in SOS v4.3)

tiltx

 = value in degrees 
The default value is 0 degrees and the values can range from -360 to 360 degrees. 

tilty

 = value in degrees
The default value is 0 degrees and the values can range from -360 to 360 degrees. 

tiltz

 = value in degrees
The default value is 0 degrees and the values can range from -360 to 360 degrees. 

timer

 = number of seconds 
Timer is used in auto presentation mode only to specifies how long to play a dataset. The default value is 180 seconds and the maximum value is 86400 seconds. 

volume

 = volume level for a dataset with audio 
MPlayer volume level for a dataset that has audio. Specify the volume keyword in a dataset playlist to override the default volume level for the duration of the dataset. The value is an integer in the range 0-100.  The default volume for the SOS video player (MPlayer) is set to 75% of the current system volume.
(New in SOS v4.3)

zfps

= frames per second 
Rate at which the zrotation feature animates. Only valid if zrotationenable is 1. Do not set this to a negative number on a dataset that rotates by default, because the sphere will behave erratically. The default value is 50 fps and the maximum value is 100,000 fps. 

zrotationangle

 = angle in degrees
Number of degrees of rotation for each time step during the zrotation. Only valid if zrotationenable is 1. Do not set this on a dataset that rotates by default, because the sphere will behave erratically. The default value is 0.1 degrees and the values can range from -360 to 360 degrees. 

zrotationenable

 = 0 OR 1 
Allows an SOS dataset to be rotated while the data is animating through time. Only supports animating around the z-axis (the axis that passes through the north and south poles). The default value is 0.

Example of Dataset playlist.sos Files 

Every dataset must have its own playlist.sos file. The following are examples of playlist.sos files for individual datasets that can be found in the /shared/sos/media directory. The include attribute should NOT be used in playlist.sos files. Every playlist.sos file must start with the name attribute and it must include either the data or layerdata attribute. All of the other attributes are optional.

name = Topography and Bathymetry with Nighttime Lights (with audio)
data = hot_topo_2048x1024.mp4
timer = 210
fps = 30
animate = 1
audio = Topography.mp3
category = land
catalog_url = http://sos.noaa.gov/Datasets/dataset.php?id=81
majorcategory = Water, Land, People

name = Pip Style Globe
data = /shared/sos/media/land/blue_marble/blue_marble/2048.jpg
pip = /shared/sos/media/extras/noaa_logo/NOAA-Transparent-Logo.png
pipstyle = globe
pipcoords = 41,-105
pipheight = 10
piptimer = 0
subcategory = my-dataset

name = Climate Model: Temperature Change (GFDL a1b) - 1870 - 2100
data = gfdl_a1b_2048.mp4
label = labels.txt
labelColor = black
endframe = 923
pip = colorbar.png
pipfadein = 0
piptimer = 0
piphorizontal = -30
firstdwell = 2000
lastdwell = 3000
category = models and simulations
catalog_url = http://sos.noaa.gov/Datasets/dataset.php?id=200
majorcategory = Air

Example of a Presentation Playlist

The following is an example of a presentation playlist that contains multiple datasets. This playlist would be located in the the sosrc directory on the SOS computer. Note that any line preceeded by a "#" symbol is a comment.

include = /shared/sos/media/land/blue_marble/blue_marble/playlist.sos

include = /shared/sos/media/astronomy/mars/original/playlist.sos
# Here, we are setting the frames per second to 20. include = /shared/sos/media/oceans/chile_tsunami/playlist.sos
fps=20

#Here, we set the stopframe
include = /shared/sos/media/oceans/japan_tsunami_waves/combo/playlist.sos
stopframe = 487

Example of a Presentation Playlist with Presenter Notes

As of SOS version 4.3.0, Presenter Notes may be added to any presentation playlist file.  Presenter notes are accessed from the iPad’s SOS Remote app’s Presentation tab, and can be edited either from the app’s Playlist Builder tab, through the Visual Playlist Editor, or manually using a text editor.  If editing a playlist file manually,  each line that is to be a presenter note should begin with “#>”.  Presenter note lines should go at the very bottom of the presentation playlist.  Following is an example.
One thing to note is that if you add presenter notes to a presentation playlist manually and then open them in the iPad app’s Playlist Builder and make edits, any normal comment lines (lines that begin with a “#” symbol) that were originally in the playlist will get deleted.

include = /shared/sos/media/land/blue_marble/blue_marble/playlist.sos

include = /shared/sos/media/astronomy/mars/original/playlist.sos

#> Features to note about blue marble:
#> - Vastness of the Sahara Desert
#> - Shading done in true color: gives Earth's appearance from space
#>
#> Features to note about mars:
#> - Olympus Mons: highest point in the solar system at 88,500 feet