playlist reference guide - science on a sphere · (new in sos v5.4) captionvisible = true or false...

Playlist Reference Guide

Version 5.4.0Nov. 19, 2018

Last modified on Jan. 7, 2020

55555555555666666666777777777788888888888

Table of Contents

Attribute/Value Pairsanimateaudiobackgroundcaptioncaptionformatcaptionheightcaptionhorizontalcaptionverticalcaptionvisiblecatalog_urlcategorycreatordatadatadirdescriptiondurationendframefirstdwellfpsframewidthiconsincludekeywordskmllegendxoffsetkmllegendyoffsetkmlpipscalelabellabelColorlabelformatlabelheightlabelhorizontallabelpositionlabelverticallabelvisiblelastdwelllayerlayeralphalayerdatalayereastlayermaxzoom

Support: Playlist Reference Guide

2

99999999

10101010101010101010111111111111111111111212121212121212121213131414

layerminzoomlayernorthlayersouthlayervisiblelayerwestmajorcategorynamepippipalphapipcoordspipdelaypipfadeinpipfadeoutpipfpspipheightpiphorizontalpipnamepippathpippathformatpipstylepiptimerpipverticalpipvisiblepipwidthpublisherrenamescriptskipstartframestopframesubcategorytiltxtiltytiltztimervolumezfpszrotationanglezrotationenable

Example of Dataset playlist.sos FilesExample of a Presentation PlaylistExample of a Presentation Playlist with Presenter Notes


3


4

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 interpretedby the main SOS application interface.

Attribute/Value Pairsanimate = 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 animateautomatically, even if animate = 0.

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

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

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

captionformat = /path/to/captionformat.htmlThe format of the caption text (i.e. font, color of text, color of background, etc.) is written as an SOS-specific htmlfile. By default, the name of the formatting file for captions is captionformat.html. This file should typically only beauto-created and/or accessed by the SOS Visual Playlist Editor. If no captionformat file is specified, the captionstext 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 degreesThe 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 longitudeThe horizontal position in degrees of the caption center. A positive value is specified as east of the center of eachprojector. The default value is 0 degrees and the value can range from -180 to 180.(New in SOS v5.4)

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

captionvisible = true or falseThe 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


5

Playlist is selected, the web page for this dataset will automatically be loaded in the Web Page tab. If the urlcannot be found, the SOS Data Catalog home page will be displayed by default.(New in SOS v4.0)

category = Deprecated attribute since SOS v4.3Replaced by the majorcategory attribute in all dataset playlists. Retained in all NOAA-managed playlists forbackward compatibility, but it is only used in SOS software (v4.3+) as a fallback value when the majorcategoryattribute 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 datasetplaylists 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 thesphere. (NOTE: WMS URL’s must be prefixed with ‘//WMS//’; see the SOS User Manual for more instructions onWMS 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 ashttp://example.com/image.jpg

datadir = Deprecated attribute since SOS v3.0Replaced 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 thebeginning 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 ofthe text. If this keyword is missing, by default the SOS software will assign site-custom datasets a descriptionvalue 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 thefirst and last frame as it loops, but the pip timing is unaffected by that. To make the pips loop as well, set theduration 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, theframe number is relative to the end of the animation. The value of the endframe can also be specified with theword "end" to specify the end of the animation. The default is the last frame and the max value is 108000.

firstdwell = number in millisecondsReferred 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 0milliseconds and the max value is 100,000 milliseconds.

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


6

http://example.com/image.jpg

framewidth = size in pixels of the data or first layerdata image or movie frame in the lateral directionSOS datasets are always rectangular with a 2:1 size ratio and this value is the larger of the two dimensions. It isused to indicate the resolution of the dataset, which is used primarily to filter high resolution datasets, i.e., greaterthan 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. Ifspecifying 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 thedegree 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 thedegree 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 wouldincrease 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 frameof the animation. This is usually used to specify a label or time stamp for an image frame sequence. Label filesare 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 framesequence) 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, AlphaThe value for each R, G, B, or Alpha parameter must be in the range [0 - 255]. The following symbolic names canalso 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


7

rendered in white color against a transparent background, and will use the Free Sans font.(New in SOS v5.3)

labelheight = value in degreesThe 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 longitudeThe horizontal position in degrees of the label center. A positive value is specified as east of the center of eachprojector. 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 latitudeThe vertical position in degrees of the label center. A positive value is specified as north of the center of eachprojector. The default value is -25 degrees and the value can range from -90 to 90.(New in SOS v5.3)

labelvisible = true or falseThe 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 0milliseconds 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 degreesThe eastern edge longitude in degrees of the layer dataset. Depending on the values specified, the layer maywrap around itself, not cover the whole, or be inverted in some fashion. If you would like a layer to cover thewhole sphere, omit the directional layer attributes. The values can range from -180 to 180. The default value is180. (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


8

1,000,000. (New in SOS v4.0)

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

layernorth = value in degreesThe northern edge latitude in degrees of the layer dataset. Depending on the values specified, the layer maywrap around itself, not cover the whole, or be inverted in some fashion. If you would like a layer to cover thewhole 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 degreesThe southern edge latitude in degrees of the layer dataset. Depending on the values specified, the layer maywrap around itself, not cover the whole, or be inverted in some fashion. If you would like a layer to cover thewhole 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 maywrap around itself, not cover the whole, or be inverted in some fashion. If you would like a layer to cover thewhole sphere, omit the directional layer attributes. The values can range from -180 to 180. The default value is180. (New in SOS v4.0)

majorcategory = main category of a NOAA-managed datasetMain 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 areall 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 onSOS 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 itsattributes such as font size and color) that will appear in a picture-in-a-picture window on the sphere. Theappearance 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 VisualPlaylist Editor.

Note that video pips only play through one time and will not repeat (see the “duration” attribute for alternate


9

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 bespecified 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 defaultvalue 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 pipshape remains constant as it moves up and down. Using the pipvertical attribute, the sides of the pip follow linesof 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 secondsThe time delay before the pip is displayed. The default value is 0 seconds, and the maximum is 86400 seconds.

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

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

pipfps = frames per second of pipThe pip playback speed in frames per second for mpeg pips and pips that play a directory of images. A defaultfps 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 degreesThe height in positive degrees of latitude. To make a pip the height of the sphere, 180 may be specified. Notethat part of the image may disappear into the black holes at the poles of the sphere. The aspect ratio of the imageor movie will be maintained unless the pipwidth attribute is also specified. The default value is 40 degrees andthe maximum value is 180 degrees.

piphorizontal = value in degrees longitudeThe horizontal position in degrees of pip center. For a pipstyle value of projector, a positive value is specified aseast of the center of each projector. See the “pipcoords” attribute for additional, relevant information. The defaultvalue 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.csvEach type of PIP can be given a simple path file that contains coordinate locations that indicate how toautomatically move the PIP on the sphere as the dataset is animating. The path file is a simple commaseparated value file (.csv file format) that contains a list of increasing frame numbers, each with a latitude and


10

longitude value. As the dataset is animating, the PIP will be moved to the location specified in the file thatcorresponds to the current frame being displayed on SOS.(New in SOS v5.4)

pippathformat = /path/to/filename.jsonA json formatted file that defines attributes related to a pippath. For example, attributes include the option to turnpath lines ON/OFF, change the color or size of path lines, etc. This file should typically only be auto-createdand/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. Apipstyle of globe places one pip on the globe, by default with a latitude and longitude of both zero. As the sphereis tilted and rotated, this pip moves with the globe. A pipstyle of room places one pip on the globe, by default withlatitude and longitude both zero. As the sphere is tilted and rotated, this pip remains stationary relative to theroom, with the sphere data moving underneath it.

piptimer = time in secondsThe length of time the pip is displayed, including fadein/fadeout (seconds). The default value is 0, which means apip image will stay on indefinitely, and a pip video will show the last frame of the video indefinitely. The maximumvalue 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 isspecified as north of the center of each projector. See the “pipcoords” keyword for additional, relevantinformation. 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 longitudeThe 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 thesphere if it is made too wide. The default value is 40 degrees and the maximum value is 360.

publisher = Deprecated attribute since SOS v4.3Previously used to indicate the name of the person or organization who published this dataset. Ignored by SOSsoftware (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 onSOS Stream GUI.

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

skip = n (where n is the skip factor for an animation through image frames (movies and directory of images))


11

skip = 1 will skip every other image frame in an animation skip = 2 will play every third image frame, etc. As skipgets bigger, the total image frames that are animated goes down. The default value is 0 and the maximum valueis 108,000.

startframe = frame numberTrim a long animation. If specified, the animation will only display frames beginning at startframe value and goingthrough endframe value. The default value is 0 and the maximum value is 108,000. Note that a startframe of 0and a startframe of 1 both correspond to the first frame in the dataset. A startframe of 2 corresponds to the 2ndframe in the dataset, and so on.

stopframe = frame number Stop animating when the animation reaches this frame number. The default value is -1 and the maximum valueis 108,000. NOTE: to start animated again after reaching the stopframe, a presenter must advance to the nextframe 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 thiskeyword is missing, the SOS software will assign site-custom datasets a subcategory = Uncategorized. Asubcategory 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 datasetplaylist.sos file AND variation dataset playlists, such as playlist_audio.sos, the subcategory keyword is ignored forvariation playlists. You must include the subcategory keyword in the playlist.sos file if you want this dataset andits 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 degreesThe default value is 0 degrees and the values can range from -360 to 360 degrees.

tiltz = value in degreesThe 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 180seconds 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 overridethe default volume level for the duration of the dataset. The value is an integer in the range 0-100. The defaultvolume 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 negativenumber on a dataset that rotates by default, because the sphere will behave erratically. The default value is 50fps and the maximum value is 100,000 fps.

zrotationangle = angle in degrees


12

Number of degrees of rotation for each time step during the zrotation. Only valid if zrotationenable is 1. Do notset this on a dataset that rotates by default, because the sphere will behave erratically. The default value is 0.1degrees 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 aroundthe 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 individualdatasets that can be found in the /shared/sos/media directory. The include attribute should NOT be used inplaylist.sos files. Every playlist.sos file must start with the name attribute and it must include either the data orlayerdata attribute. All of the other attributes are optional.

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

name = Pip Style Globedata = /shared/sos/media/land/blue_marble/blue_marble/2048.jpgpip = /shared/sos/media/extras/noaa_logo/NOAA-Transparent-Logo.pngpipstyle = globepipcoords = 41,-105pipheight = 10piptimer = 0subcategory = my-dataset


13

https://sos.noaa.gov/support/manuals/dataset-manual/#dataset-playlistsos-files

name = Climate Model: Temperature Change (GFDL a1b) - 1870 - 2100data = gfdl_a1b_2048.mp4label = labels.txtlabelColor = blackendframe = 923pip = colorbar.pngpipfadein = 0piptimer = 0piphorizontal = -30firstdwell = 2000lastdwell = 3000category = models and simulationscatalog_url = http://sos.noaa.gov/Datasets/dataset.php?id=200majorcategory = Air

Example of a Presentation PlaylistThe following is an example of a presentation playlist that contains multiple datasets. This playlist would belocated in the the sosrc directory on the SOS computer. Note that any line preceeded by a "#" symbol is acomment.

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.sosfps=20

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

Example of a Presentation Playlist with Presenter Notes


14

https://sos.noaa.gov/support/manuals/presentation-manual/

As of SOS version 4.3.0, Presenter Notes may be added to any presentation playlist file. Presenter notes areaccessed from the iPad’s SOS Remote app’s Presentation tab, and can be edited either from the app’s PlaylistBuilder 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 bottomof 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 theiPad app’s Playlist Builder and make edits, any normal comment lines (lines that begin with a “#” symbol) thatwere 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


15

playlist reference guide - science on a sphere · (new in sos v5.4) captionvisible = true or false...

Documents