Asterisk Jukebox, "Tape Cartridge" Player, & Wizard

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.

Asterisk Jukebox Wizard (AJW) is a shell script for generating the dialplan that interfaces with the player logic. It was formally it's own project, but has been merged in to this one.

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.

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/(optionalfolder)/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.

By design, one would be generating entry extension/contexts using the wizard. But it is possible to use it manually with the above information.

Asterisk Jukebox Wizard (ajw) HOWTO

The script automatically generates the album entry extensions, I've made every effort to make sure they're in numerical order. If you want a specific order, prefix your folder names.

The automatic nature of the script does require your folder/files to already be in place. By default, the script looks in /var/lib/asterisk/sounds/en for what you specify to be the jukebox root. If they are one directory deeper in your default sounds; you can specify that in the configuration. Examples:

• /var/lib/asterisk/sounds/en/jukeboxroot/albums - All jukeboxes live in $asd
• /var/lib/asterisk/sounds/en/astjuke/jukeboxroot/albums - Jukebox roots live under another folder (in this case, astjuke/)

You can modify the location of your Asterisk Sounds directory by modifying the asd= line at the beginning of the script.

Once the files are in place and you have read access, run the script and answer the prompts:

"Pick a name/identifier for this jukebox:" - name used for dialplan context

"Enter the folder your jukebox roots live under:" - if your roots live under another 
folder (because network mount/symlink), enter it here. Blank means no addtional path.

"Enter the root folder name of your jukebox:" - folder in sounds that contain
all your albums

"Enter the filename of your menu/intro:" - name of file played when answered.
lives in juke root.

"How many times do you want it to play?" - how many times to play the intro
before hanging up

"How many seconds between intro play?" - how many seconds between intro
 playback

"Enter the filename of your exit file:" - name of file played before hangup.
lives in juke root.

"Enter A Channel Volume:" - Tell the Volume function to set a volume. Defaults to -3

The script now automatically enumerates sub-folders, counts tracks, determines leading zero, and writes the appropiate dialplan. You must prefix your folders with numbers if you want to ensure they are a specific order.

Make sure the conf file is included in your extensions.conf somehow; the same for tapecart-player.conf.

[globals]
#include $name-juke.conf

Then it's just a matter of directing a call to it's context (usually s,$name-juke)

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

22-SEP-2022: Merge ajw repo. Make script pass shellcheck. 
21-SEP-2022: Add some sanitization. Broke repositories. Fixed 'em.
14-AUG-2022: Fix cartplayer extension fallthrough. Add HOWTHISWORKS.MD. Added ajw.sh
06-MAY-2022: Update Readme. Add conf/examples. 
05-MAY-2022: Initial Commit to self-hosted git.

Explanation of Operation

A full breakdown is in HOWTHISWORKS.MD

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/>.