Asterisk Jukebox & "Tape Cartridge" Player

Asterisk Jukebox & "Tape Cartridge" Player is a pair of scripts that provides a jukebox like interface for playing songs/albums stored on the server, as well as logic to perform this playback.

About

Asterisk Jukebox & Player consist of two basic dialplans:

a common set of logic for playback called from a jukebox interface
a jukebox interface dialplan for music/album selection

There is no reason you cannot use the player outside of a jukebox, provided you set all the variables and call the proper extensions in it's context.

tapecart-player.conf is provided as it's own .conf file. It should go without saying you only need to include this file in your extensions.conf. If you run a big flat extensions.conf, then you probably already know to copy/paste it in.

Tracks are selected using a 4-digit code that consists of album number and track number. Track "00" is special and will play the full album from the beginning. During album playback; repeat, skip, and back controls are provided. Pressing "0" will also take you back to the main menu.

Playback logic uses internal counters to request files. This requires your files contain ONLY a track number, with or without leading zero. Only two digits for a maximum of 99 tracks are supported. Playback logic's context is called using extension pattern matching which dictates leading zero behavior and passes some album information.

A related project, ajw - asterisk jukebox wizard, provides a bash script that creates the jukebox interface for you.

How To Use/Setup

Asterisk Jukebox depends heavily on your files being stored in a specific way; each album is it's own folder, all filenames are track numbers, and the jukebox folder lives in Asterisk's sounds directory.

/var/lib/asterisk/sounds/en/jukeboxroot/album/[(0)1-99].ulaw

Include tapecart-player.conf (or tryinclude), or it's contents, in to your extensions.conf.

tapecart-player.conf provides two contexts:

[cart-player] - provides single track playback [8track-player] - provides album playback

For both contexts, the following variables will need to be set before sending a channel to them:

c - the context you are sending from (used for returning from player) aa - the path relative to your asterisk sounds directory your files live.

Both contexts use pattern matching extensions to select behavior as well as pass information.

[cart-player]

#X - with X being 1 - 9 for files without leading zeros
*XX - with XX being all tracks > 10 or with leading zeros

[8track-player]

#XX - with XX being the number of tracks plus one. files without leading 0.
*XX - with XX being the same as above, but files with leading 0. 

The idea is to keep the 4-digit leading zero code compatible with files that don't have leading zeros. Originally I just forced leading zeros. But, naturally; setting a variable to "01" and adding one to it results in "2", which is not equal to "02" and causes playback to fail. Some of the logic for cart-player is done at the jukebox dialplan for dealing with lack of leading zeros; because sometimes you EXTEN:-2 and sometimes you want to EXTEN:-1.

Using The Jukebox

When you dial the extension you're greeted with your intro file. You then need to enter a 4 digit code comprised of the album and track number:

1234
| |_________Track number
|___________Album number

Track number "00" is special and when entered, will play the entire album back from the beginning. In album playback, the following controls affect playback:

1 - skips back a track 2 - repeats the current track 3 - skips ahead a track

At the end of the album, or at any time during playback; pressing 0 returns to the main menu.

Single track playback returns to the main menu at the end of the track, or by pressing 0.

History

05-MAY-2022: Initial Commit to self-hosted git.
06-MAY-2022: Update Readme. Add conf/examples. 

Explanation of Operation

Rather than just write a script to generate a massively large dialplan with everything hard-coded; the playback logic was designed to be universal and uses extensions to configure parts of it.

From your jukebox dialplan, the first two digits of entry are hard-coded and set the folder location for those tracks. The last two digits are pattern matched. If they're 00, it calls the appropiate extension 8track-player. Otherwise it calls the proper extension for cart-player; using additional logic for leading 0s.

For single track playback (cart-player context), two pattern matching extensions are used:

#X - with X being 1 - 9 for files without leading zeros
*XX - with XX being all tracks > 10 or with leading zeros

The only difference between them is how many digits you send and how many it pulls from the "dialed extension". Pound and asterisk are used as a pre-fix to avoid conflict with 1,2,3, and 0 controls.

For album playback, the situation is quite similar:

#XX - with XX being the number of tracks plus one. files without leading 0.
*XX - with XX being the same as above, but files with leading 0. 

When you call the aprpropiate extension, the player determines if the track number is less than 10 so it can write that variable appropiately. It then sets a variable to either # or *, depending which was used. This variable is used for the playback controls.

If your files don't have the leading zero (sent to #), then the routine simply plays a track, increments the counter, compares it to the track count, and then sends it back to playback or not. For channels sent to * because you have leading zeros, a few additional steps are done. Rather than jump directly to playback; we check to see if current track has hit ten. If not, continue as usual. But when you do hit track 10, we jump to a couple of lines that change the varible from pound to star, and then dump us in to the context at normal playback. We then finish the remainder of the album looping through the pound extension.

License

Asterisk Jukebox
Copyright (C) 2022 Jay Moore - nq4tango@gmail.com

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.