Playlist Format Reference
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 that are read and interpreted by the main SOS application interface.
animate
Permalink to animateanimate = [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
Permalink to audioaudio = [/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
Permalink to backgroundDeprecated attribute since SOS v4.0. Replaced by layer attributes.
caption
Permalink to captioncaption = [/path/to/file.srt]
New in SOS v5.4
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.
captionformat
Permalink to captionformatcaptionformat = [/path/to/captionformat.html]
New in SOS v5.4
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.
captionheight
Permalink to captionheightcaptionheight = [value in degrees]
New in SOS v5.4
The height in positive degrees of latitude. (Note that the width of the caption is automatically computed.)
captionhorizontal
Permalink to captionhorizontalcaptionhorizontal = [value in degrees longitude]
New in SOS v5.4
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.
captionvertical
Permalink to captionverticalcaptionvertical = [value in degrees latitude]
New in SOS v5.4
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.
captionvisible
Permalink to captionvisiblecaptionvisible = [true or false]
New in SOS v5.4
The initial visibility of the caption when loaded. The default value is false.
catalog_url
Permalink to catalog_urlcatalog_url = [url_of_dataset]
New in SOS v4.0
The SOS Data Catalog url that corresponds to the dataset. On the deprecated iPhone, 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 Datasets home page will be displayed by default.
category
Permalink to categorycategory
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
Permalink to creatorcreator = 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
Permalink to datadata = [/path/to/data]
This is required 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 Dataset’s Manual on WMS 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
Permalink to datadirdatadir
Deprecated attribute since SOS v3.0. Replaced by the data and layerdata atrributes.
description
Permalink to descriptiondescription = {{ text }}
New in SOS v5.0
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. Please note that there cannot be any newlines within the text (i.e. do not press Enter or Return within the {{ }}). 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.
duration
Permalink to durationduration = [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
Permalink to endframeendframe = [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
Permalink to firstdwellfirstdwell = [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
Permalink to fpsfps = [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
Permalink to framewidthframewidth = [size in pixels of the data or first layerdata image or movie frame in the lateral direction]
New in SOS v4.0
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.
icons
Permalink to iconsicons = [/path/to/filename]
New in SOS v4.0
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.
include
Permalink to includeinclude = [/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
Permalink to keywordskeywords = `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
Permalink to kmllegendxoffsetkmllegendxoffset = [degree of longitude offset]
New in SOS v4.1
By default KML legends and ancillary graphics are placed at 180 degrees longitude. Use this factor to specify the degree to offset the legends.
kmllegendyoffset
Permalink to kmllegendyoffsetkmllegendyoffset = [degree of latitude offset]
New in SOS v4.1
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.
kmlpipscale
Permalink to kmlpipscalekmlpipscale = [scale factor]
New in SOS v4.1
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.
label
Permalink to labellabel = [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
Permalink to labelColorlabelColor
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
Permalink to labelformatlabelformat = [/path/to/labelformat.html]
New in SOS v5.3
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.
labelheight
Permalink to labelheightlabelheight = [value in degrees]
New in SOS v5.3
The height in positive degrees of latitude. (Note that the width of the label is automatically computed.)
labelhorizontal
Permalink to labelhorizontallabelhorizontal = [value in degrees longitude]
New in SOS v5.3
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.
labelposition
Permalink to labelpositionlabelposition = [default OR x,y (Note no space after the comma.)]
Deprecated attribute since SOS v5.3
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
Permalink to labelverticallabelvertical = [value in degrees latitude]
New in SOS v5.3
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.
labelvisible
Permalink to labelvisiblelabelvisible = [true or false]
New in SOS v5.3
The initial visibility of the label when loaded. The default value is true.
lastdwell
Permalink to lastdwelllastdwell = [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
Permalink to layerlayer = [name]
New in SOS v4.0
Creates a new layer with the given name, which may contain spaces and continues to the end of the line.
layeralpha
Permalink to layeralphalayeralpha = [opacity of layer]
New in SOS v4.0
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.
layerdata
Permalink to layerdatalayerdata = [/path/to/data]
New in SOS v4.0
Specifies the data file that will be loaded into the new layer (NOTE: WMS URL’s must be prefixed with ‘//WMS//’. See the SOS Dataset’s Manual on WMS for more instructions on WMS URL’s.)
layereast
Permalink to layereastlayereast = [value in degrees]
New in SOS v4.0
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.
layermaxzoom
Permalink to layermaxzoomlayermaxzoom = [value]
New in SOS v4.0
The max zoom value that the layer will appear at when using the magnifying glass. The default and max value is 1,000,000.
layerminzoom
Permalink to layerminzoomlayerminzoom = [value]
New in SOS v4.0
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.
layernorth
Permalink to layernorthlayernorth = [value in degrees]
New in SOS v4.0
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.
layersouth
Permalink to layersouthlayersouth = [value in degrees]
New in SOS v4.0
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.
layervisible
Permalink to layervisiblelayervisible = [true OR false]
New in SOS v4.0
The initial visibility of the layer when loaded. The default value is true.
layerwest
Permalink to layerwestlayerwest = [value in degrees]
New in SOS v4.0
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.
majorcategory
Permalink to majorcategorymajorcategory = [main category of a NOAA-managed dataset]
New in SOS v4.3
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.
name
Permalink to namename = [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
Permalink to pippip = [/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
Permalink to pipalphapipalpha = [pip opacity]
Opacity of pip over underlying image. Minimum = 0.0 (invisible) Maximum = 1.0 (completely opaque). The default value is 1.0.
pipcoords
Permalink to pipcoordspipcoords = [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
Permalink to pipdelaypipdelay = [time in seconds]
The time delay before the pip is displayed. The default value is 0 seconds, and the maximum is 86400 seconds.
pipfadein
Permalink to pipfadeinpipfadein = [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
Permalink to pipfadeoutpipfadeout = [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
Permalink to pipfpspipfps = [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
Permalink to pipheightpipheight = [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
Permalink to piphorizontalpiphorizontal = [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
Permalink to pipnamepipname = [name]
New in SOS v5.2
The name of the pip. Defaults to the pip filename if not specified.
pippath
Permalink to pippathpippath = [/path/to/filename.csv]
New in SOS v5.4
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.
pippathformat
Permalink to pippathformatpippathformat = [/path/to/filename.json]
New in SOS v5.4
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.
pipstyle
Permalink to pipstylepipstyle = [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
Permalink to piptimerpiptimer = [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
Permalink to pipverticalpipvertical = [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
Permalink to pipvisiblepipvisible = [true OR false]
New in SOS v5.2
The initial visibility of the pip when loaded. The default value is true.
pipwidth
Permalink to pipwidthpipwidth = [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
Permalink to publisherpublisher
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
Permalink to renamerename = [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
Permalink to scriptscript = [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
Permalink to skipskip = [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
Permalink to startframestartframe = [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. Note that a startframe of 0 and a startframe of 1 both correspond to the first frame in the dataset. A startframe of 2 corresponds to the 2nd frame in the dataset, and so on.
stopframe
Permalink to stopframestopframe = [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
Permalink to subcategorysubcategory = [subcategory for a site-custom dataset]
New in SOS v4.3
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.
tiltx
Permalink to tiltxtiltx = [value in degrees]
The default value is 0 degrees and the values can range from -360 to 360 degrees.
tilty
Permalink to tiltytilty = [value in degrees]
The default value is 0 degrees and the values can range from -360 to 360 degrees.
tiltz
Permalink to tiltztiltz = [value in degrees]
The default value is 0 degrees and the values can range from -360 to 360 degrees.
timer
Permalink to timertimer = [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
Permalink to volumevolume = [volume level for a dataset with audio]
New in SOS v4.3
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.
zfps
Permalink to zfpszfps = [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
Permalink to zrotationanglezrotationangle = [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
Permalink to zrotationenablezrotationenable = [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: Dataset Playlist File
Permalink to Example: Dataset Playlist FileEvery 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.
Example: Presentation Playlist File
Permalink to Example: Presentation Playlist FileThe 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.
Presenter Notes
Permalink to Presenter NotesAs 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.