From 0036cc13016ae2accb3e8435cf3ff07c7d7427fc Mon Sep 17 00:00:00 2001 From: Loren Moore Date: Fri, 6 May 2022 16:23:49 -0400 Subject: [PATCH] Update Readme. Add .conf files --- README.md | 180 +++++++++++++++++++++++++++++++++++++++++++ example-juke.conf | 23 ++++++ tapecart-player.conf | 37 +++++++++ 3 files changed, 240 insertions(+) create mode 100644 example-juke.conf create mode 100644 tapecart-player.conf diff --git a/README.md b/README.md index e69de29..05c2ece 100644 --- a/README.md +++ b/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 . + + diff --git a/example-juke.conf b/example-juke.conf new file mode 100644 index 0000000..65c0e16 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/tapecart-player.conf b/tapecart-player.conf new file mode 100644 index 0000000..a37d9fe --- /dev/null +++ b/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) \ No newline at end of file