asterisk_jukebox/README.md

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

The ajw.sh script will generate the configuration dialplans for you.


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

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