UC-1 Output playlist to single file

ref# UC-1
use case Output playlist to single sound file
type primary, essential
actors
purpose To output a playlist to a single sound file, which can then be used in a number of ways, especially podcasting.
overview The ‘output playlist to single sound file’ contacts Local Storage to retrieve a playlist and its component files. These files are then ‘played’ through the sound engine, which renders them to a single sound file, complete with all fades and transitions. The user is then prompted on where to save the file, and given three options: 1) to add it to the LS database 2) to save it locally. In addition, the user should have a check box that would enable them to use the file in a podcast. In the event the podcast option is chosen (described in ticket #1496), the user will be prompted to choose a location to save the file, as well as an option to edit the fields of the metadata describing the file. The actual RSS feed would map LiveSupport’s relevant metadata.
references Storage server interface: #1599; Gstreamer interface: #690.

Typical course of events

actor action
system response
1 User selects option to output playlist as single file from playlist editor or scratchpad context menu 2 The system gathers all files referenced by the playlist
3 The system passes all files referenced by the playlist to the sound engine, which combines them and includes all transitions described in playlist
4 The system prompts user for file save location
5 User chooses playlist save location 6.1 If the user chooses to save the file into the LiveSupport system, the File Upload window opens
6.2 If the user chooses to save the file to the local filesystem, a filesystem window opens
6.3 If the user chooses to save as podcast, a prompt appears asking if the user wants to edit the file's metadata. Podcast RSS files are generated automatically by the system. The new RSS file could be either created if none exists in the specified location, or appended to an existing one. Settings for items such as file location and number of items in the RSS file would be handled in station preferences.

XML-RPC interfaces

Storage

(see #1599*) Three separate function sequences for the scenarios 6.1, 6.2 and 6.3.

for 6.1:

renderPlaylistToStorageOpen

  • input:
    • sessid
    • plid
  • output:
    • token

renderPlaylistToStorageClose

  • input:
    • token
  • output:
    • status
    • (if "success") gunid : string - the ID of the AudioClip created
    • (if "fault") faultCode, faultString

The audio clip metadata should contain most of the metadata of the original playlist, with some extra info, like date created.

for 6.2:

renderPlaylistToFileOpen

  • input:
    • sessid : string
    • plid : string
  • output:
    • token : string - a token identifying this transaction
    • (or a fault response; I will not write this from now on)

renderPlaylistToFileCheckStatus

  • input:
    • token
  • output:
    • status : string - one of "success", "working" or "fault"
    • (if "success") url : string - readable URL of the ogg file
    • (if "fault") faultCode, faultString

renderPlaylistToFileClose

  • input:
    • token
  • output:
    • nothing if there are no errors

After Close, the ogg file is deleted from the Storage Server.

for 6.3:

renderPlaylistToRSSOpen

  • input:
    • sessid
    • plid
  • output:
    • token

renderPlaylistToRSSCheckStatus

  • input:
    • token
  • output:
    • status
    • (if "success") url : string - readable URL of RSS XML metafile
    • (if "fault") faultCode, faultString

renderPlaylistToRSSClose

  • input:
    • token
  • output:
    • nothing if there are no errors

After CheckStatus, the ogg file is publicly available at a URL which is contained in the RSS XML metafile. After Close, the RSS XML metafile is deleted from the Storage Server.

Gstreamer

(see #690)

Option 1: the Gstreamer executable uses xml-rpc (UC-5) to get a SMIL representation of the playlist.

  • input:
    • -c --config : path to a configuration file
    • -p --playlist : unique ID of the playlist to be rendered
    • (-s --sessid : a session ID needed for authentication) -- unnecessary?
    • -o --output : file name where the output will be written
  • output:
    • 0 on success, non-zero on errors

Option 2: the Storage Server prepares the SMIL file in advance, and passes the location of this to the executable.

  • input:
    • -p --playlist : the URL of a playable SMIL file
    • -o --output : file name where the output will be written
  • output:
    • 0 on success, non-zero on errors

in terms of output, would you need to track the progress of processing the audio file? it might take some time, so you might want to be able to track where it stands...

we could provide machine-readable progress output to stdout, something like dots for every percent of progress made, or a numeric percentage number for every percent of progress made?