ajw/README.md

# ajw - Asteisk Jukebox Wizard

Builds a dialplan to make Asterisk function as a jukebox.


## About

An Asterisk Jukebox is a IVR that mimics the function of a CD jukebox. It
currently supports playing single tracks or full albums. Selections are made
using a 4 digit code; album number and track number. Basic playback controls
are available during album play to skip back, ahead, and repeat track.

jaw is a wizard for building the jukebox dialplan. After uploading your files
in the proper folder/filename convention, just answer the jaw's questions; it
will automagically spit out a jukebox dialplan.

## 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
```

The 1.0 update to jaw sees it become ajw. The difference is that ajw now makes
dialplans that do not include playback logic. This is now a seperate file.

You no longer tell it how many albums you have, how many folders, or tracks.
The script now automatically does all of this; and as a result, albums are added
in directory list 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 the default asterisk directory; and that you can read it during execution. This
may require you to run the script as root. If your default directory isn't
/var/lib/asterisk/sounds/en then you must modify 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 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.

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

```
11-MAY-2022 - Fatal error in accidently escaped character fixed.
07-MAY-2022 - Initial Commit
```

# Explanation of Generated Dialplan

The dialplan has undergone some extensive changes since last update. The
use of While has been eliminated as it caused some problems. The way some
things are done have been drastically changed (hopefully for the better). Some
of this was necessitated by the wizard; some of it was in spite of the wizard. 

```
[examplejuke-main]
exten = s,1,Answer()
same =n,Set(VOLUME(TX)=-3)
same = n,Set(c=examplejuke-main)
same = n(loop),Background(foobar/menu)
same = n,WaitExten(5)
same = n,Set(m=$[${m} + 1])
same = n,GoToIf($["${m}" < "5"]?loop)
same = n,Background(foobar/bye)
same = n,Hangup()

```

After being answered, we set not just the channel volume but the context name.
Most of this is just looping the intro.

```
exten = _00XX,1,Set(aa=cleverlys/01cleverlys)
same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,*13,1)
same = n,GoToIf($["${EXTEN:-2}" < "10"]?cart-player,\#${EXTEN:-1},1)
same = n,GoTo(cart-player,*${EXTEN:-2},1)

exten = _01XX,1,Set(aa=cleverlys/02cashcrop)
same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,*07,1)
same = n,GoToIf($["${EXTEN:-2}" < "10"]?cart-player,\#${EXTEN:-1},1)
same = n,GoTo(cart-player,*${EXTEN:-2},1)

exten = _02XX,1,Set(aa=cleverlys/03blue)
same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,*13,1)
same = n,GoToIf($["${EXTEN:-2}" < "10"]?cart-player,\#${EXTEN:-1},1)
same = n,GoTo(cart-player,*${EXTEN:-2},1)
```
We no longer write the last two of the extension to a variable, we just call it
directly from now on. We also now use that as the extension we dial in the
single playback routine. We call either an extension starting with # or *
depending on the leading zero situation. AJW handles writing all of this.

A full explanation of how the jukebox works, including explanation of
tapecart-player.conf is at the repository:
https://git.pickmy.org/dewdude/Asterisk_Jukebox

# License

    ajw - Asterisk Jukebox Wizard
    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/>.