Update Readme. Add .conf files

README.md

@@ -0,0 +1,180 @@
+# 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 an 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
+
+    jaw - jukebox for asterisk wizard
+    Copyright (C) 2021 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/>.
+
+

example-juke.conf

@@ -0,0 +1,23 @@
+[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()
+
+exten = _00XX,1,Set(aa=foobar/00album)
+same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,*11,1)
+same = n,GoTo(cart-player,*${EXTEN:-2},1)
+
+exten = _01XX,1,Set(aa=foobar/01album)
+same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,*15,1)
+same = n,GoTo(cart-player,*${EXTEN:-2},1)
+
+exten = _02XX,1,Set(aa=foobar/02album)
+same = n,GoToIf($["${EXTEN:-2}" = "00"]?8track-player,#12,1)
+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)

tapecart-player.conf

@@ -0,0 +1,37 @@
+[cart-player]
+exten = _#X,1,Wait(.25)
+same= n,Background(${aa}/${EXTEN:-1})
+same = n,Goto(${c},s,return)
+exten = _*XX,1,Wait(.25)
+same= n,Background(${aa}/${EXTEN:-2})
+same = n,Goto(${c},s,return)
+exten = 0,1,Goto(${c},s,return)
+
+[8track-player]
+exten = _*XX,1,Set(tt=${IF($[${EXTEN:-2} < 10]?${EXTEN:-1}:${EXTEN:-2})})
+same = n,Set(t=1)
+same = n,Set(p=*)
+same = n(lead),GoToIf($[${t} = 10]?tenplus)
+same = n(hax),Background(${aa}/0${t})
+same = n(next),Set(t=$[${t} + 1])
+same = n,GoToIf($[${t} < ${tt}]?lead)
+same = n,Goto(${c},s,goodbye)
+same = n(tenplus),Set(p=#)
+same = n,GoTo(#00,hax)
+exten = _#XX,1,Set(tt=${IF($[${EXTEN:-2} < 10]?${EXTEN:-1}:${EXTEN:-2})})
+same = n,Set(t=1)
+same = n,Set(p=#)
+same = n(hax),Background(${aa}/${t})
+same = n(next),Set(t=$[${t} + 1])
+same = n,GoToIf($[${t} < ${tt}]?hax)
+same = n,Goto(${c},s,goodbye)
+
+exten = 1,1,GoToIf($["${t}" = "1"]?wait)
+same = n,Set(t=$[${t} - 1])
+same = n(wait),Wait(.25)
+same = n,Goto(${p}00,hax)
+exten = 2,1,Wait(.25)
+same = n,Goto(${p}00,hax)
+exten = 3,1,Wait(.25)
+same = n,Goto(${p}00,next)
+exten = 0,1,Goto(${c},s,return)