Playlist and Library Commands

While most SOS automation commands apply to the current clip, those in this section apply to the playlist as a whole. An SOS playlist is a set of clips, numbered from one through the number of clips in the playlist.

fadein [fade_duration]

The fadein command fades the sphere in from black. The fade_duration parameter specifies the number of seconds over which to fade in from black. If the fade_duration is not specified, the default fadein duration is used. This command is called automatically after a clip is loaded.

fadeout [fade_duration]

The fadeout command fades the sphere to black. The fade_duration parameter specifies the number of seconds over which to fade to black. If the fade_duration is not specified, the default fadeout duration is used. This command is called automatically before a clip is unloaded.

get_all_name_value_pairs [clip_number]

The get_all_name_value_pairs command returns a list of name-value pairs for all the parameters specified for the given clip_number in the currently loaded playlist. The syntax of the returned list is derived from the Tcl scripting language, and is a single line containing a set of space delimited name-value pairs. Each name-value pair is also space delimited. If the value contains internal spaces, it is enclosed in curly braces. If the value itself contains curly braces, they and other special characters may be further escaped with backward slashes.

Once a clip is loaded, many of the clip attributes can be modified by the automation interface. The get_all_name_value_pairs command returns the initial values of those attributes as recorded in the playlist, even if they have changed since the clip was loaded.

The get_clip_count command returns the total number of clips in the currently loaded playlist.

get_clip_info [clip_number | * clip_parameter]

The get_clip_info command returns information about a clip as specified within the currently loaded playlist.

The first command argument is required, and is the clip number, or an asterisk for all clips.

The second command argument is optional, and is the name of the clip parameter as specified in the playlist. The default parameter is the name of the clip.

Once a clip is loaded, many of the clip attributes can be modified by the automation interface. The get_clip_info command returns the initial values of those attributes as recorded in the playlist, even if they have changed since the clip was loaded.

The value returned by the get_clip_info command has a different format depending on whether a specific clip number was requested, or the asterisk was used to request all clips. If a specific clip number was given, the return value is one line, with the value of the requested parameter (or an empty line if the parameter was not specified for this clip). If the asterisk was used to request all clips, the return value is a set of lines, one per clip, with a final line consisting of the character “R” to indicate the end of the list. The line for each clip in this case is the clip number followed by a space character, optionally followed by the parameter value for that clip (if specified in the playlist).

get_clip_list_from_file [filename]

The get_clip_list_from_file command returns an unsorted list of all the name-value pairs of each clip found in the filename, where filename is the absolute path to a .sos playlist file. The syntax of the returned list is derived from the Tcl scripting language, and is a single line containing a set of space delimited name-value pairs (see the get_all_name_value_pairs command for more information on the Tcl syntax).

Each name tag in a name-value pair is prepended by the clip’s sequential number in the playlist file (for example: 2,category, where category is the name tag).

Note that there are two extra name-value pairs always included in the return list:

• 0,animate value (where value is 0 or 1)
• size value (where value is the number of clips in the playlist)

In addition, there is one extra name-value pair for each clip that is always included in the return list, but is not present in the clip’s .sos file:

• #,valid value (where # is a clip number in the playlist, and value is 0 or 1)

get_clip_list_from_file "~/sosrc/myplaylist.sos"
1,opengl true 1,publisher NOAA size 2 0,animate 0 1,category land 2,publisher {NASA GSFC} 1,fps 40 2,fps 30 2,name {Helium Sun} 2,pipcount 0 1,tiltx 23.5 2,category astronomy 0,valid 1 1,valid 1 1,creator NASA 2,creator {NASA GSFC} 2,valid 1 1,name {Blue Marble (23 degree tilt)} 1,datadir /shared/sos/media/land/blue_marble/blue_marble/4096.jpg 2,datadir /shared/sos/media/astronomy/helium_sun/helium_sun_2048.mp4 1,pipcount 0

The get_clip_number command returns the number of the currently playing clip. Clips in the playlist are numbered from one to the total number of clips in the playlist.

If the currently playing clip is not part of the current playlist, get_clip_number returns 0. This happens when a new playlist is loaded while a clip continues to play.

If no clip is currently playing, get_clip_number returns -1.

The get_playlist_name command returns the filename of the current presentation playlist. If no presentation playlist is currently loaded, it returns an empty line.

load [filename | dirname]

The load command loads an individual global image file (or directory of files) without the context of a playlist. Ordinarily, data sets are viewed as defined by a clip within a playlist, but this command allows loading an image file without editing a playlist. A temporary clip, number 0, is created when this command is used.

The next_clip command stops any currently playing clip, clears the sphere, and plays the next clip sequentially in the playlist. If the last clip was playing, it jumps to the first clip.

open_clip_list [clip_list]

The open_clip_list command clears the currently loaded playlist and loads and opens a new temporary playlist in SOS Stream GUI containing all the clips in clip_list. clip_list is a Tcl list of name-value pairs for a set of clips (for example, a list that is in the format returned by the get_clip_list_from_file command).

open_playlist [playlist_file]

The open_playlist command loads a new playlist file. If the playlist_file name starts with a forward slash character, it specifies an absolute path name. Otherwise, it specifies a file relative to ~/sosrc (the sosrc directory in the user’s home directory). Any currently playing clip continues to play after a new playlist is loaded.

open_playlist /shared/sos/media/land/blue_marble/blue_marble/playlist.sos

open_playlist normal-demo.sos

overlay [filename | dirname | clip_number]

The overlay command creates a new layer on top of any existing global data, and loads the specified global image file or directory of files to the new layer. The new layer is created with default attributes which can then be changed with the layer command. When an integer clip_number is specified, the global image layers of that clip are loaded as new layers on top of any existing global data.

playlist_delete [playlist_file]

The playlist_delete command deletes the specified presentation playlist file, which is required to use a relative path under the presentation playlist directory ~/sosrc.

playlist_delete mysubdir/playlist.sos

playlist_exists [playlist_file]

The playlist_exists command checks to see if the specified playlist file exists. The playlist is required to use a relative path under the presentation playlist directory ~/sosrc or a full path under a NOAA dataset directory (i.e., under /shared/sos/media or /shared/sos/rt/noaa).

playlist_exists /shared/sos/media/site-custom/mysubdir/myplaylist.sos

playlist_read [playlist_file]

The playlist_read command opens and reads the contents of the specified playlist file, which is returned as a string. The playlist is required to use a relative path under the presentation playlist directory ~/sosrc or a full path under the NOAA dataset directory (i.e., under /shared/sos/media or /shared/sos/rt/noaa).

playlist_read /shared/sos/media/site-custom/mysubdir/myplaylist.sos

playlist_rename [from_playlist_file] [to_playlist_file]

The playlist_rename command renames (i.e., moves) the specified playlist file to a new name. Both the “from” and “to” playlist_files are required to use a relative path under the presentation playlist directory ~/sosrc and the “to” playlist_file cannot be for an existing file. Existing subdirectories within ~/sosrc may be specified, but new subdirectories are not created by this command.

playlist_rename myplaylist.sos mysubdir/myplaylist2.sos

playlist_write [playlist_file] [playlist_text]

The playlist_write command writes a playlist-formated text string into the specified playlist file, creating it, if necessary. Ends of lines in the text are indicated by “\n”. The playlist is required to use a relative path under the presentation playlist directory ~/sosrc. Existing subdirectories within ~/sosrc may be specified, but new subdirectories are not created by this command.

playlist_write myplaylist.sos “# comment\ninclude=/shared/sos/media/site-custom/playlist.sos\n#> presenter note\n”

The prev_clip command stops any currently playing clip, clears the sphere, and plays the previous clip sequentially in the playlist. If the first clip was playing, it jumps to the last clip.

search_clip_list [search_term] [clip_list list_of_tags]

The search_clip_list command is identical to the search_clip_list_from_file command (see below). The only difference is the second parameter, clip_list. clip_list is a Tcl list of name-value pairs for a set of clips (for example, a list that is in the format returned by the get_clip_list_from_file command).

search_clip_list_from_file [search_term] [playlist_file] [list_of_tags]

The search_clip_list_from_file command searches through the name-value pairs of each clip in the playlist_file and returns all of the name-value pairs of only those clips where each of the search terms were present somewhere in the clip’s values.

The first command argument is the term or terms to be searched for. Multiple search terms should be enclosed in quotation marks (ex. “carbon aerosol”).

The second command argument is the absolute path to a .sos playlist file.

The third command argument, list_of_tags, selects a specific name tag to search in the clip’s sos playlist file. There are three options:

Search only the values paired with the name tag.

Search only the values paired with the keywords tag.

The empty string means search all tags specified for the clip.

Multiple tags may be specified by enclosing them in quotation marks (ex. “name keywords”). Note that at least on of the above options must be specified.

In the return list of search results, each name tag in a name-value pair is prepended by the clip’s number in the playlist file (for example: 2,category, where category is the name tag).

Note that there is one extra name-value pair for each clip that is always included in the list that is not found in the clip’s .sos file: 0,valid value (where value is 0 or 1).

search_clip_list_from_file "helium sun" "~/sosrc/__library__/all.sos" name
196,publisher {NASA GSFC} 196,datadir /shared/sos/media/astronomy/helium_sun/helium_sun_2048.mp4 196,valid 1 196,name {Helium Sun} 196,pipcount 0 196,category astronomy 196,fps 30 196,creator {NASA GSFC}

set_auto_presentation_mode [0 | 1]

The set_auto_presentation_mode turns on or off (0 = off, 1 = on) the auto presentation (or auto run) mode of SOS. While in auto presentation mode, the system automatically advances from one clip to the next. The system plays each clip the number of seconds that are specified by the timer value for that clip in the current playlist. If no timer value is specified for the clip, a system default time is used (typically 2 or 3 minutes per clip).

set_fadeout_duration [seconds]

The set_fadeout_duration command sets the default duration in seconds for subsequent fadeouts.

set_fadein_duration [seconds]

The set_fadein_duration command sets the default duration in seconds for subsequent fadeins.