Terminal application specifications
From AutOKwiki
This is a functional description for the autOKfe Terminal Program. It will describe the following.
- General Purpose and Goals of the Terminal Program
- Expected behavior of the Terminal Program
- Expected interactions with the Server
Note this is not a detailed specification, the programmer is responsible for writing a program that adheres to this description. The programmer is also encouraged to write a true specification of the program and enter it into the autOKwiki pages.
Contents |
General Purpose and Goals
The purpose of the autOKfe Song Queue Terminal program is to offer a simple user interface to the AutoKDJ song queue mechanism, that does not have the EUE limits or security risks imposed by a pure web front end run by a standard web browser. It will also program hardware that is located on the local terminal server, such as a Barcode Reader for ticket authentication.
Development Guidelines
The Song Queue Terminal Program will be developed using the following general guidelines:
- Simple User Interface: Each page only shows controls or asks questions necessary to perform a single task at a time.
- Reskinnable: Front end that can be easily "re-skinned", using a simple overlay or bitmap scheme.
- Written in C/C++ over Win32: This language and UI model is chosen so it can run efficiently on any conceivable Windows computer (even a P200 MHz)
- Minimize the use of prompts: Only make the user click on an OK button if it is absolutely necessary.
- Intuitive Behavior: The user interface should always tend to do the actions that make common sense. Keep in mind that customers using the kiosk may not be at their full mental capacity when using it. For example:
- When presented with screens that have multiple possible actions, NO actions should result in a failure or a lack of progress.
- No apparently live buttons or controls should be dead. Dead buttons or controls should be preferably invisible, or greyed out.
- Buttons or controls that indicate forward progress should be VERY obvious.
- Appropriate for a Kiosk: Should be a fullscreen application, blocks alt-tab, task manager, Start bar and and any other attempts to get to underlying Windows interface. Access to the Windows interface should be permitted only with a password.
Use with autOKdj
You must be using autOKdj Plugin for Winamp (Remote Control Server), in order for the below-mentioned functionality regarding HTTP posts to work.
For use with song and user ID tickets, AutoKDJ should be configured in the following manner:
- Your printed tickets should match the format specified in Ticket Format Specification
- Under Karaoke Preferences, turn ON Strict Ticketing
- Under Venue UID, enter a random 8 digit hexadecimal number. This value should match the value that is printed on the song ticket in the Venue_ID field in both Song and User tickets. See Ticket Format Specification for format details.
- Under Master Song UID, enter a different 8 digit hexadecimal number. This is provided as a skeleton key, so while debugging you need not worry about expiring tickets. This should be the value under Ticket_ID for Song Tickets in your testing. A song ticket with this value and the correct Venue_ID will never expire. See Ticket Format Specification for format details.
- If you run into trouble with expiring tickets, you may unexpire all tickets by deleting the following file: {Winamp Root}/Plugins/ml_www/akdjtikt.txt Note this file is on the server that runs Winamp and autOKdj.
- To test the User ID tickets, you must construct the list of singers and their IDs. Technical implementation details for developing a singer - UID correspondence are TBD.
- An individual user ticket should have the numeric value in the first column of the above mentioned file IN HEXADECIMAL NOTATION as the Ticket_ID field in User tickets.
- If you cannot print your own tickets, then you may do all of the above with this one difference: In autOKdj, Under Karaoke Preferences, turn OFF Strict Ticketing. This should result in the proper parsing of HTTP ticket posts, including identifying users and ticket upgrades, but will not require specific Venue_ID or Ticket_ID values, other than matching the appropriate number of characters.
Behavior and Functional Description
Notes
Note that much of the below-mentioned functionality can be easily prototypted without a working back end.
The behavior and functional description is based upon the process described in the AutoKDJ Process Description.
Some hints for the below functionality can be obtained with the following:
'http://{server}/karaoke.txt?query=?CONFIG'
This will return data in the format:
CONFIG : VENUENAME: AutoKDJ VENUE UID: CLOSING TIME: 1:30 TICKETING USED: 0 TICKETING ENFORCED: 0 MAX SINGER REPEAT: 0 USE STANDBY QUEUE: 0 AUTO START: 1 KEYCHANGE LOWER LIMIT: -12 KEYCHANGE UPPER LIMIT: 12 TEMPO LOWER LIMIT: -50 TEMPO UPPER LIMIT: 100
Note that order of these fields is not guaranteed, only the names.
This is only available when using AutoKDJ 1.0 RC1 or greater.
All pages
The following description and functional behavior applies to all pages. When writing software for a given page, please do not forget these parts! This may be best implemented in a modular fashion, using C++ interitance or subclassing or whatever.
Start Over A Start Over button should be viewable on all pages. If clicked, immediately advance to Page 1.
Monitor Sold Out Before advancing from any page to any other page, check the Sold Out message, as described below under Page 1. If the Number of Songs left is ever equal to 0, immediately advanced to Page 1.
Timeout For all pages other than page 1, if 30 seconds passes and the user has not made forward progress, advise the user to hurry up. If another 30 seconds passes, bring up a screen saying
Sorry, Time Is Out. Please See The Songbook and Return Later
Then wait 5 seconds, then proceed to Page 1.
For page 1, use the same timeout to merely refresh all data without the warning messages.
Page 1: Welcome Page
Page 1: Text Displayed:
(Welcome Message Here) (Songs Left Message Here) Please Scan Your Song Ticket
Text in (Welcome Message Here) is queried from the server via an HTTP post:
http://{server}/karaoke.txt
Data is returned in the following format:
WELCOME : DISP: Welcome to AutoKDJ
Text in (Songs Left Message Here) is queried from the server via an HTTP post:
http://{server}/karaoke.txt?query=%3FNUMSONGSTOCLOSE
The server will return the following TEXT format:
CLOSEMSG : DISP: NOTE: There are approximately 128 songs left until we are sold out. VAL : 128
The data displayed to the user should be the text that follows 'DISP'
The text following 'VAL' will always be a decimal (base 10) representation of the number of songs that users can enter before the show is sold out. If the value of after VAL : is zero, do NOT show anything more on this page.
Note in a certain mode of operation, the KDJ can configure the server to "never close". 24-hour Karaoke Place maybe? Or just wants to control the show? Who knows. But it can happen.
In this case the text will be:
CLOSEMSG : DISP: VAL : 4294967295
In this condition, just do what it says... display no sold out message, and behave as if there are over 4 billion songs until we are sold out.
While idle and showing this screen, the Terminal Program continually refreshes the screen, so as to get an accurate value for VAL :
If VAL : is not zero, program also waits for a ticket to be scanned. If VAL : is zero, scanner is not read.
Per the ticket format specification, a Song Ticket will contain 18 characters. These characters should be held for future reference. If the ticket does not contain exactly 18 characters, it should be rejected as non authentic. If the first 2 digits are not 00, the ticket should be rejected.
If it passes these two tests, the ticket should be validated with the server using the following HTTP post:
http://{server}/karaoke.txt?query=?VALIDATE ?TICKET_VENUEID=12345678 _TICKETPURP=00 _TICKETID=9ABCDEF0
- The numbers following VENUEID= are digits 3 through 10 on the Song Ticket.
- The numbers following TICKETPURP= are digits 1 through 2 on the Song Ticket.
- The numbers following TICKETID= are Digits 11 through 18 on the Song Ticket.
The server will return with one of the following two replies in text format:
AUTHENTICATION : STATUS: NOT VALID DISP: One or more of your tickets is not valid. Please see the KDJ for assistance.
This reply means the ticket is not valid. The text next to DISP: should be shown to the user, the screen should hold for 5 seconds, then reset to Page 1.
AUTHENTICATION : STATUS: VALID
This reply means the ticket is valid. Upon receiving this message, the user is then taken to Page 2.
Page 2: Name Entry Page
Text Displayed:
(Welcome Message Here) (Songs Left Message Here) Please Enter Your Name: [Text Box] If You Have Sung Earlier, You May Choose Your Name Here: [Combo Box] If You Have An ID Card, You May Scan It Now
[Text Box] A text box is exposed here, for the user to enter a name.
[Combo Box] A combo box is exposed here, for the user to select a name. The list of names is queried from the server via the following HTTP post:
http://{server}/karaoke.txt?query=%3FPREVIOUSSINGERLIST
The server will return the following TEXT format:
SINGER:
DISP: Mike
HTML: Mike
URL : Mike
{random data}
SINGER:
DISP: Karen & Jacob
HTML: Karen & Jacob
URL : Karen%20%26%20Jacob
{random data}
Each unique singer will begin with the SINGER: header.
- DISP: shows what should be displayed on the AutoKDJ screen.
- HTML: shows text that is safe to put into an HTML page. (May not be accurately depicted above)
- URL : shows text that is safe to enter into a URL, and that should be used in followup messages.
The terminal application should be prepared to accept and ignore any {random data} that follows. This data could be debugging information or other bits that may be needed by other system components.
Text or Combo Box Behavior
If the user enters their name manually using the Text Box, or selects a name using the Combo box, this name should be authenticated. This is to cater for the scenario where the KDJ has placed a limitation on the number of singers that may be in the song queue at any time.
To do this, send the following HTTP post to the server:
http://{server}/karaoke.txt?query=?ADDUSER+"{URL Friendly Text Name Here}"
It is important to note that the FE will have to do a URL encode of the text data before sending it to the server. A simple URL encoding algorithm already exists in the AKDJ back end, and can be provided if necessary.
If it is OK for this name to be used at this time, you will receive a response saying:
AUTHENTICATION : STATUS: VALID
Otherwise, the FE will receive a response saying:
AUTHENTICATION : STATUS: NOT VALID DISP: You may not enter a song at this time. Please see the KDJ for assistance.
The text after "DISP: " is what should be displayed to the customer. 5 seconds later, return to Page 1.
Upon entry of a name and successful authentication if needed, advance to the next page.
User ID Card Behavior
autOKfe should continually Look for data from the barcode scanner. When a ticket it scanned, its info is read. Per the Ticket Format Specification, a Song Ticket will contain 18 characters. These characters should be held for future reference. If the ticket does not contain exactly 18 characters, it should be rejected as non authentic. If the first 2 characters of the ticket are not 01, the ticket should be rejected as non authentic. All remaining authentication occurs at the final HTTP post.
In order to display a friendly name, send the following HTTP post to the server:
http://{server}/karaoke.txt?query=?SELECTUSER ?TICKET_VENUEID=12345678 _TICKETPURP=01 _TICKETID=9ABCDEF0
- The numbers following VENUEID= are digits 3 through 10 on the User Ticket.
- The numbers following TICKETPURP= are digits 1 through 2 on the User Ticket
- The numbers following TICKETID= are Digits 11 through 18 on the User Ticket.
If this is a valid user ID, the post will return the following data in TEXT format:
USERID : STATUS: VALID DISP: Mike G ONLINE : ZuGzUg SANG: 0 INQUEUE: 0 LASTROTATION: 0 ROTATIONIDX: 0
The text next to DISP: is what should be displayed to the user as {Name} in the subsequent pages. The ticket values should be remembered, as they will be reused in a subsequent post. Note that since this is an encoded ticket value, you need not have the URL safe user name, as was needed above.
If this is not a valud user ID, the post will return the following data in TEXT format:
USERID : STATUS: NOT VALID DISP: This User ID card is not recognized. Please use one of the other fields, or see the KDJ for assistance.
Upon encountering STATUS: NOT VALID, the text next to DISP : should be displayed for 5 seconds, and then this page should be refreshed.
Upon entry of a name and successful authentication if needed, advance to the next page.
Page 3: Song Entry Page
Page 3: Text Displayed
(Welcome Message Here), {Name}
(Songs Left Message Here)
If You Know the CD-ID, Enter That Here: [Text Box 1]-[Text Box 2]
Please Select Your Song From The Following List. [List Box]
To Search Songs For Artist Or Title, Enter Search Text Here: [Text Box 3]
If You Have Your Own Karaoke CD, Click Here: [Button 1]
{Name} is the name that was entered on page 2.
[Text box 1]-[Text box 2] is for the user to enter the CD ID. Valid text is xxx-yy, where xxx is a number that indicates the "Album" and yy is a number that indictes the "Track". If values in proper format are entered here, the terminal program does an HTTP post to search for Album=xxx, Track=yy.
This post takes on the following format:
http://{server}/karaoke.txt ?query=?ALBUM+%3D%3D+%22158%22+AND+TRACKNO+%3D%3D+%2211%22
The significance of this post is a query for CD-ID.
The text in bold needs to be substituted by the application, all other text may remain as it is, verbatim.
If found, the server will respond with a post in the following TEXT format, indicating the Song Title, Song Original Artist, a "Song Already Sung" Flag, Album Name, Track Number, the Media Library Index, and a Hash Code for the song.
SONGQUERY :
RES : 1
SONG :
ARTIST: Metallica
TITLE : Enter Sandman
CD-ID : 158-11
INDEX : 1
HASH : 346893681
PLAYED: 0
{random data}
The terminal application should be prepared to accept and ignore any {random data} that follows. This data could be debugging information or other bits that may be needed by other system components.
System now proceeds to Page 4.
[List Box] A table is displayed here with the previous search results. If this is the first time the page is displayed, the list box is omitted. The columns are as follows:
- Artist (Artist name here)
- Title (Title here)
- Sung? (use * to indicate a song that was queued or sung earlier)
- CD-ID (CD-ID here, in xxx-yy format)
The user is now able to sort by either Artist or Title, and may select one entry. CD-ID comes from the Album Name and Track Number. These should be numeric values, xxx-yy. If they are not, do not put anything in this column.
If the user selects a song, proceed to Page 4.
[Text Box 3] is used for users to search for songs.
Any text is valid. the terminal program does an HTTP post to search for Anything LIKE the text that was entered.
http://{server}/karaoke.txt?query={URL safe version of mlQueryStruct.query field}
Examples:
To search for "Artist LIKE Cars":
http://{server}/karaoke.txt?query=%3Fartist%20LIKE%20%22Cars%22
These URLs are IDENTICAL to those that are generated using the normal ml_www page. The only exception is the fact that you are now using karaoke.txt as the page name.
All entries that match that criteria will be returned to the terminal in TEXT format. For each entry, the Song Title, Song Original Artist, Album Name, Track Number, a "Song Already Sung" Flag, a Media Library Index, and a Hash Code are returned.
SONGQUERY :
RES : 3
SONG :
ARTIST: Cars
TITLE : You Might Think
CD-ID : 158-5
INDEX : 2
HASH : 2323299893
PLAYED: 0
{random data}
SONG :
ARTIST: Cars
TITLE : Shake It Up
CD-ID : 1-5
INDEX : 7
HASH : 3451863199
PLAYED: 0
{random data}
SONG :
ARTIST: Cars
TITLE : Tonight She Comes
CD-ID : 15-5
INDEX : 12
HASH : 175535374
PLAYED: 0
{random data}
Note RES : indicates the number of results to expect. If there are 200 or more results, there will be a + after the value, i.e.
RES : 200 +
All values displayed are decimal (base 10) values.
The terminal application should be prepared to accept and ignore any {random data} that follows. This data could be debugging information or other bits that may be needed by other system components.
System now refreshes this page.
If [Button 1] is pressed, this means the custoemr has a custom CDG. For now, this will simply queue up a song that is called CustomCDG. So, simply search for that file, make sure the server actually has it, and then proceed to Page 4.
Page 4: Song Confirm Page
Page 4 is shown when the user narrows down a single song.
Page 4: Text Displayed:
(Welcome Message Here), {Name}
(Songs Left Message Here)
You Have Selected:
{Artist Name} {Song Title} {CD-ID}
Is This Correct? [Yes Button] [No Button]
If You Would Like To Buy Upgrades, click here [Upgrade Button]
A yes and no buttons are displayed. If yes is selected, proceed to Page 6. If no is selected, go back to Page 3.
If [Upgrade Button] is pushed, go to Page 5.
Page 5: Upgrade Page
Page 5 should look similar to the Song Ticket user interface of the Welcome page, except that it should be able to accept multiple tickets, and have the following additional elements.
Tickets Entered: [List Box] Upgraded with xx tickets All Upgrade Tickets Entered [Button 1] Cancel All Upgrade Tickets [Button 2]
Look for data from the barcode scanner now. For each ticket that is scanned and authorized, increase the "bump count" by one. Refresh the screen, with text indicating the upgrade
Each user is limited to 5 upgrade tickets.
Per the Ticket Format Specification, each Song Ticket will contain 18 characters. These characters should be held for future reference. If the ticket does not contain exactly 18 characters, it should be rejected as non authentic. If the first 2 digits are not 00, the ticket should be rejected.
If it passes these two tests, the ticket should be validated with the server using the following HTTP post:
http://{server}/karaoke.txt?query=?VALIDATE? ?TICKET_VENUEID=12345678 _TICKETPURP=00 _TICKETID=9ABCDEF0
This format, response and expected behavior is identical to the ticket validation format for a song ticket, as described in Page 2.
Once any ticket is validated, its information should be saved for use on Page 6.
When 5 tickets have been entered, the system should not permit any new tickets to be entered, but should present all other options.
If the user clicks on [Button 2], all upgrade ticket information is remembered and the system advances back to page 4.
If the user clicks on [Button 1], all upgrade ticket information is forgotten and the system advances back to page 4.
Page 6: Confirm and Submit page
Page 6 is shown when the user confirms the song.
At this point, the Terminal "Invalidates" all song and upgrade tickets scanned, so they may no longer be reused.
It does this by sending a final HTTP post that actually queues the song. This will be a post that contains the singer name and ID, the hash code of the song they selected, and the number of upgrade bumps they bought.
Per the Ticket Format Specification, the following is the format of this post.
If the user selected their name from a combo box, or entered their name manually, use the following HTTP Post:
http://{server}/karaoke.txt?query=?ENQUEUE?USER={URL SAFEUSERNAME} ?song={library index}_{hash code} ?TICKET_VENUEID=12345678 _TICKETPURP=00 _TICKETID=9ABCDEF0
{URL SAFE USERNAME} is the data that was in the URL : portion of the Name of a Repeat Customer. For New Customers, this needs to be generated in a URL safe manner.
The significance of the numbers is:
- {library index}_{hash code} returned from the previous Song Query.
- Number following VENUEID= is digits 3 through 10 on the Song Ticket
- Number following TICKETPURP= is digits 1 through 2 on the Song Ticket
- Number following TICKETID= is digits 11 through 18 on the Song Ticket
If upgrades were purchased, each ticket should be presented in succession, i.e.:
http://{server}/karaoke.txt?query=?ENQUEUE?USER={URL SAFE USERNAME} ?song={library index}_{hash code} ?TICKET_VENUEID=12345678 _TICKETPURP=00 _TICKETID=9ABCDEF0 ?TICKET_VENUEID=12345678 _TICKETPURP=00 _TICKETID=9ABCDEF1
If the user selected their name from a User ID card, the URL is the same, except the ?USER section is replaced with the ticket info
http://{server}/karaoke.txt?query=?ENQUEUE ?song={library index}_{hash code} ?TICKET_VENUEID=12345678 _TICKETPURP=01 _TICKETID=00000002 ?TICKET_VENUEID=12345678 _TICKETPURP=00 _TICKETID=9ABCDEF0
Note this is just a concatination of tickets, but one of those tickets is a User ticket instead of a Song ticket.
The format of the User ticket is identical to the format described in the User ticket section of Page 3.
Upon this post, all tickets will be authenticated.
If *any* of the tickets are not authentic or invalid, a page in TXT format containing an error message will be returned to the client.
AUTHENTICATION : STATUS: NOT VALID DISP: One or more of your tickets is not valid. Please see the KDJ for assistance.
The text after "DISP: " is what should be displayed to the customer. 5 seconds later, return to Page 1.
Otherwise, the following text is then displayed.
Page 6: Text Displayed:
Thank You, {Name}.
Please Hold Onto Your Tickets, and Give Them to the KDJ When You Sing!
After 5 seconds, the Terminal Program proceeds to Page 1.
