diff --git a/README.md b/README.md
index 5e7b835..e10ab12 100644
--- a/README.md
+++ b/README.md
@@ -1,89 +1,88 @@
-# ajw - Asteisk Jukebox Wizard
-
-Builds a dialplan to make Asterisk function as a jukebox.
+# 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
-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.
+Asterisk Jukebox & Player consist of two basic dialplans:
-## Requirements
-You will need to have the `func_volume.so` and `func_logic.so` loaded in order
-to use Asterisk Jukebox. Add these to `modules.conf`
+- a common set of logic for playback called from a jukebox interface
+- a jukebox interface dialplan for music/album selection
-## 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.
+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.
-```
-/var/lib/asterisk/sounds/en/(optional-subfolder)/jukeboxroot/album/[(0)1-99].ulaw
-```
+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.
-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.
+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.
-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.
+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.
-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. Example:
+A related project, **[ajw - asterisk jukebox wizard](https://git.pickmy.org/dewdude/ajw)**, provides a bash script that
+creates the jukebox interface for you. This will give more information as to how the script works.
-`/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
-
-You can modify the location of your Asterisk Sounds directory by modifying the
-`asd=` line at the beginning of the script.
+## How To Use/Setup
-Once the files are in place and you have read access, run the script and answer
-the prompts:
+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.
```
-"Pick a name/identifier for this jukebox:" - name used for dialplan context
+/var/lib/asterisk/sounds/en/jukeboxroot/album/[(0)1-99].ulaw
+```
-"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.
+Include tapecart-player.conf (or tryinclude), or it's contents, in to your
+extensions.conf.
-"Enter the root folder name of your jukebox:" - folder in sounds that contain
-all your albums
+tapecart-player.conf provides two contexts:
-"Enter the filename of your menu/intro:" - name of file played when answered.
-lives in juke root.
+- [cart-player] - provides single track playback
+- [8track-player] - provides album playback
-"How many times do you want it to play?" - how many times to play the intro
-before hanging up
+For both contexts, the following variables will need to be set before sending a
+channel to them:
-"How many seconds between intro play?" - how many seconds between intro
- playback
+- c - the context you are sending from (used for returning from player)
+- aa - the path relative to your asterisk sounds directory your files live.
-"Enter the filename of your exit file:" - name of file played before hangup.
-lives in juke root.
+Both contexts use pattern matching extensions to select behavior as well as
+pass information.
-"Enter A Channel Volume:" - Tell the Volume function to set a volume. Defaults to -3
-```
+[cart-player]
-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.
+```
+#X - with X being 1 - 9 for files without leading zeros
+*XX - with XX being all tracks > 10 or with leading zeros
+```
-Make sure the conf file is included in your extensions.conf somehow; the same
-for tapecart-player.conf.
+[8track-player]
```
-[globals]
-#include $name-juke.conf
+#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.
-Then it's just a matter of directing a call to it's context (usually s,$name-juke).
## Using The Jukebox
@@ -112,72 +111,21 @@ pressing 0.
# History
```
-21-SEP-2022 - Add subfolder option - track sanitization for cart-player
-14-AUG-2022 - Fixed missed (goodbye) label in setup context.
-12-AUG-2022 - Doesn't write delay if you set Delay to 0.
-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.
-
+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.
```
-[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(goodbye),Background(foobar/bye)
-same = n,Hangup()
-```
+# Explanation of Operation
-After being answered, we set not just the channel volume but the context name.
-Most of this is just looping the intro.
+A full breakdown is in HOWTHISWORKS.MD
-```
-exten = _00XX,1,Set(aa=foobar/00album)
-same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,*11,1)
-same = n,GoToIf($["${EXTEN:-2}" > "19"]?9999)
-same = n,GoTo(cart-player,*${EXTEN:-2},1)
-same = 9999,Playback(option-is-invalid)
-same = n,GoTo(examplejuke-main,s,1)
-
-exten = _01XX,1,Set(aa=foobar/01album)
-same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,*15,1)
-same = n,GoToIf($["${EXTEN:-2}" > "19"]?9999)
-same = n,GoTo(cart-player,*${EXTEN:-2},1)
-same = 9999,Playback(option-is-invalid)
-same = n,GoTo(examplejuke-main,s,1)
-
-exten = _02XX,1,Set(aa=foobar/02album)
-same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,#12,1)
-same = n,GoToIf($["${EXTEN:-2}" > "19"]?9999)
-same = n,GoToIf($["${EXTEN:-2}" < "10"]?cart-player,#${EXTEN:-1},1) ; these files don't have a leading zero
-same = n,GoTo(cart-player,*${EXTEN:-2},1)
-same = 9999,Playback(option-is-invalid)
-same = n,GoTo(examplejuke-main,s,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/src/master/HOWITWORKS.MD
# License
- ajw - Asterisk Jukebox Wizard
+ Asterisk Jukebox
Copyright (C) 2022 Jay Moore - nq4tango@gmail.com
This program is free software: you can redistribute it and/or modify
@@ -193,4 +141,3 @@ https://git.pickmy.org/dewdude/Asterisk_Jukebox/src/master/HOWITWORKS.MD
You should have received a copy of the GNU General Public License
along with this program. If not, see .
-
diff --git a/ajw.README b/ajw.README
new file mode 100644
index 0000000..5e7b835
--- /dev/null
+++ b/ajw.README
@@ -0,0 +1,196 @@
+# 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.
+
+## Requirements
+
+You will need to have the `func_volume.so` and `func_logic.so` loaded in order
+to use Asterisk Jukebox. Add these to `modules.conf`
+
+## 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/(optional-subfolder)/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 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. Example:
+
+`/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
+
+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
+
+```
+21-SEP-2022 - Add subfolder option - track sanitization for cart-player
+14-AUG-2022 - Fixed missed (goodbye) label in setup context.
+12-AUG-2022 - Doesn't write delay if you set Delay to 0.
+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(goodbye),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=foobar/00album)
+same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,*11,1)
+same = n,GoToIf($["${EXTEN:-2}" > "19"]?9999)
+same = n,GoTo(cart-player,*${EXTEN:-2},1)
+same = 9999,Playback(option-is-invalid)
+same = n,GoTo(examplejuke-main,s,1)
+
+exten = _01XX,1,Set(aa=foobar/01album)
+same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,*15,1)
+same = n,GoToIf($["${EXTEN:-2}" > "19"]?9999)
+same = n,GoTo(cart-player,*${EXTEN:-2},1)
+same = 9999,Playback(option-is-invalid)
+same = n,GoTo(examplejuke-main,s,1)
+
+exten = _02XX,1,Set(aa=foobar/02album)
+same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,#12,1)
+same = n,GoToIf($["${EXTEN:-2}" > "19"]?9999)
+same = n,GoToIf($["${EXTEN:-2}" < "10"]?cart-player,#${EXTEN:-1},1) ; these files don't have a leading zero
+same = n,GoTo(cart-player,*${EXTEN:-2},1)
+same = 9999,Playback(option-is-invalid)
+same = n,GoTo(examplejuke-main,s,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/src/master/HOWITWORKS.MD
+
+# 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 .
+
+