The pl_elem music player program

The Juke_Box custom server invokes this program which takes audio data from a source and passes it to a music channel.

This music player plays tunes as loops. That is, when the end of the file is reached, the player starts again at the beginning and continues until the player is stopped.

Specify parameters in the Juke_Box custom server configuration file, or as a field on the juke_box_configure_music custom server action. These parameters are passed to the music player when it starts.

The source of the audio data is a file which contains a list of element structures produced by CA_import_voice().

Use cvelem to produce these files. See cvelem (Convert to elements program).

Parameter string syntax

-f filename

[-a] 

[-er max_elements_per_read] 

[-eb elements_to_buffer]

[-ew max_elements_per_write]

[-hw high_water_mark]

[-lw low_water_mark]

[-pr preferred_elements_per_read]

Parameters

The -f filename parameter is mandatory. All the other parameters are optional and have defaults.

-f filename

A mandatory parameter. The name of the file containing the source data of the music player. The filename must include a path name, either the full path name, or the path name relative to the Juke_Box custom server directory ($DB/current_dir/ca).

-a

An optional parameter. Specifies that the source file is loaded into memory before the tune is played to the music channel. This is efficient for small source files, because the data is held locally in page space rather than on the file system.

Do not set this parameter for large files; they use large amounts of page space and this can degrade system performance.

-er max_elements_per_read

An optional parameter. Specifies the maximum number of 1600-byte blocks which are read from the source file at a time. Making this number large enough improves system performance, making it too large reduces it.

-eb elements_to_buffer 

An optional parameter. Specifies the maximum number of 1600-byte blocks cached by pl_elem internally. The music player reads ahead to fill this buffer. If this number is larger than the file itself, it has the same effect as using the -a flag.

If the music channel under-runs, and you have already tried to correct it using the high and low water mark options, specify a larger buffer space here.

-ew max_elements_per_write

An optional parameter. Specifies the maximum number of 1600-byte blocks which are written to the music channel at a time.

-hw high_water_mark

An optional parameter. The level of the high water mark for this player’s music channel.

The high water mark is the maximum number of 4 KB buffers (mbufs) that can be used to buffer music data destined for the music channel. When this value is high, more memory is used, and more data is needed to fill the buffer initially.

This value must be higher than the value of the low water mark parameter. The range for this parameter is 2 to MAX_MUSIC_HIGH_WATER.

This parameter overrides the default value (DEF_MUSIC_HIGH_WATER) for the high water mark for the music channel. If music channels underrun, increase this number. See Figure 1 for an example of how this is used.

-lw low_water_mark

An optional parameter. The level of the low water mark for this player’s music channel.

The low water mark is the number of 4 KB buffers (mbufs) which defines the level at which insufficient data is buffered ready to be sent to the music channel. When the amount of buffered data falls below this level, POLLOUT is activated, indicating to the Juke_Box custom server that more data is needed in the buffer to avoid under-running. High values in this parameter reduce the chance of an underrun on this channel, but more memory is needed and there is an increased the load on the system when the music channel is started.

This parameter overrides the default value (DEF_MAX_MUSIC_LOW_WATER) for the low water mark for the music channel. If music channels underrun, increase this value to give a longer delay between pl_elem being called by CA_Poll, and writing to the music channel. See Figure 1 for an example of how this is used.

This parameter must be less than high water mark. The range for this parameter is 1 to MAX_MUSIC_LOW_WATER.

-pr preferred_elements_per_read

An optional parameter. The preferred number of elements obtained from the source of the music data at one time. The music player uses this number to optimize the number of read from source operations, and how much data is read each time.