This music player program reads a segment from the Blueworx Voice Response database into a buffer which the custom server interface sends to the music channel.
This music player plays tunes as a continuous loop. That is, when the end of the segment is reached, the player starts again at the beginning. It continues until the player is stopped by the Juke_Box custom server when it receives the juke_box_stop_music command.
The Juke_Box custom server starts and passes parameters to pl_seg when it receives the juke_box_start_music command and stops pl_seg when it receives the juke_box_stop_music command. Specify parameters for pl_seg in the Juke_Box custom server configuration file, or as a field in the juke_box_configure_music command.
Parameter string syntax
-d directory name
-l language code
-s segment number
[-a]
[-er max_elements_per_read]
[-ew max_elements_per_write]
[-eb elements_to_buffer]
[-hw high_water_mark]
[-lw low_water_mark]
[-pr preferred_elements_per_read]
Parameters
- -d directory_name
- A mandatory parameter. A string parameter. The name of the voice directory containing the segment. This string can be up to 100 characters long, with no spaces or tabs.
- -l language_code
- A mandatory parameter. The language number of the voice directory. The range of this parameter is 1 to MAX_LANGUAGE inclusive.
- -s segment_number
- A mandatory parameter. This is the segment number in the voice directory to be used by the music player. The range of this parameter is 1 to USHRT_MAX.
- -a
- An optional parameter. Indicates that the whole of the segment is to
be loaded into memory before writing to the music channel. This can cause
a delay initially because the tune can take longer to start, but when the
whole tune is in memory, the player does not have to get any of voice data
again.
Do not set this parameter for large files because they will use large amounts of page space and degrade system performance.
- -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 player uses this number to optimize the number of read-from-source operations performed, and how much data is read each time.
- -er max_elements_per_read
- An optional parameter. The maximum number of segment elements which are read at a time from the Blueworx Voice Response segment database.
- -ew max_elements_per_write
- An optional parameter. The maximum number of elements written to the music channel at a time.
- -eb elements_to_buffer
- An optional parameter. The number of elements the player uses as a buffer.
- -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 MIN_MUSIC_HIGH_WATER to MAX_MUSIC_HIGH_WATER. You can use the default value, DEF_MUSIC_HIGH_WATER. 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, a CA_Poll on the music channel returns indicating to the music player 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.
This value must be less than the value of the high water mark parameter.
The range for this parameter is MIN_MUSIC_LOW_WATER to MAX_MUSIC_LOW_WATER. You can use the default value, DEF_MUSIC_LOW_WATER. See Figure 1 for an example of how this is used.
Figure 1. High and Low Water Marks
In Figure 1, at point 1, CA_Open_Music_Channel opens the music channel. The buffer is empty. CA_Poll reports that the buffer is below the low water mark and that the channel is under-running.
At point 2, the buffer is filled to the high water mark (the buffer is full). Blueworx Voice Response starts sending data to the music channel, draining the buffer.
At point 3, the level of data in the buffer falls below the low water mark, CA_Poll reports this to the music player which refills the buffer to the high water mark. The time between points 3 and 4 is the time between the polling and refilling of the buffer. This process repeats until the music player stops.