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