AutOKdvd Functional Specification
From AutOKwiki
General Purpose and Goals The purpose of the CD Burning Terminal Program is to offer a nice user interface that allows customers to purchase individual songs in CD-G format, or videos of themselves singing in VCD format, or combinations of both in on a single CD. The program will then immediately burn the CD, offering instant satisfaction for the customer. It will also program hardware that is located on the local terminal server, such as the CD Burner.
The CD Burning Terminal Terminal Program will be developed using the following general guidelines:
* Simple User Interface, where each page only shows controls or asks questions necessary to perform a single task at a time.
* Front end that can be easily "re-skinned", using a simple overlay or bitmap scheme.
* Written in C/C++ over Win32, so it can run efficiently on any conceivable Windows computer (even a P200 MHz)
* Appropriate for a Kiosk
o Should be a fullscreen application
o Blocks alt-tab, task manager, Start bar and and any other attempts to get to underlying Windows interface
o Access to the Windows interface should be permitted only with a password
Points of Note You must be using ml_www_autokdj Alpha 2.14 or better, in order for the below-mentioned functionality regarding HTTP posts to work. You can get the Alpha 2.14 build at http://www.7bamboo.com/files/zip/ml_www_autokdj_a2.14.zip
For use with user ID tickets, Alpha 2.14 or greater should be configured in the following manner:
* Your printed tickets should match the format specified in AutoKDJ Ticket Authentication Strategy * 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 AutoKDJ Ticket Authentication Strategy 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 AutoKDJ Ticket Authentication Strategy for format details. * If you run into trouble with expiring tickets, you may unexpire all tickets by deleting the following file: o {Winamp Root}/Plugins/ml_www/akdjtikt.txt * Now, to test the User ID tickets, you must construct the list of singers and their IDs. For the purposes of this project, do the following: o Browse to http://www.7bamboo.com/pootie.php o Select all the contents of the resulting page o Using Notepad, create a new file called {Winamp Root}/Plugins/ml_www/akdjuser.txt o Paste all contents of this page into this file o Save the file. * 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. Note the values in the above file are DECIMAL and therefore MUST BE CONVERTED. See AutoKDJ Ticket Authentication Strategy for format details. (As it turns out, the value 00000555 is yours truely... :-P)
If you cannot print your own tickets, then you may do all of the above with this one difference:
* 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.
Note that much of the below-mentioned functionality can be easily prototypted without a working back end.
Note that much of the below-mentioned functionality is similar if not identical to the AutoKDJ Song Queue Terminal Application Specification. It is highly recommended that similar if not the same software be used for the CD Burning Terminal Program, for consistent look and behavior. Behavior and Functional Description The behavior and functional description is based upon the process described in the AutoKDJ Process Description. Page 1: Introduction Page Page 1: Text Displayed:
(Welcome Message Here) Text in parenthesis is queried from the server via an HTTP post:
Data is returned in the following format:
WELCOME :
DISP: Welcome to AutoKDJ
The text after "DISP: " is what should be displayed to the customer.
Please Enter Your Name: text box is exposed here, for the user to enter a name.
If You Have Sung Earlier, You May Choose Your Name Here: 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. Probably not needed here.
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.
If You Have An ID Card, You May Scan It Now Look for data from the barcode scanner now. When a ticket it scanned, its info is read. Per the AutoKDJ Ticket Authentication Strategy, 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://localhost/karaoke.txt?query=?SELECTUSER? ?TICKET_VENUEID=12345678_TICKETPURP=01_TICKETID=9ABCDEF0
The significance of the numbers in red bold is: Digits 3 through 10 on the User ID Ticket
The significance of the numbers in blue bold is: Digits 1 through 2 on the User ID Ticket
The significance of the numbers in purple bold is: Digits 11 through 18 on the User ID 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 rememberd, 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 this, the text next to ERROR should be displayed for 5 seconds, and then this page should be refreshed.
User now enters their name. If they enter their name in the text box, and that name matches one that is on the Sung Earlier List, ask to confirm.
This takes them to the next page.
NOTE: For ANY AND ALL PAGES after Page 1
The following behavior should ensue:
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 Return Later". Then proceed to Page 1.
CD % Full Formula: Each CD can hold up to either 15 Karaoke Songs, or XX Videos. Each Video Takes Up the Space of YY Karaoke Songs. Each Video will also come with a Karaoke Song, as we are making it such that when a customer buys a video, they also get the song they sung in CD-G format.
QUESTION: How Many Videos in VCD Format can a CD hold? That will tell us XX and YY. Page 2: Name Entry and Selection Page Page 2: Text Displayed:
(Welcome Message Here), {Name} {Similar to Page 1} {Name} is the name that was entered on page 2.
Your CD Is Now (x%) Full This shows running gauge showing how much of the CD is Full, based on previous selections.
You Have Selected the Following Videos: {Artist Name} {Song Title} The above is displayed only if the user had previously selected videos. Click Here If You Would Like To Change Your Performance Video Selection! button is exposed here, for the user to indicate they want their videos. If clicked, proceed to Page 3.
You Have Selected the Following Karaoke Songs: {Artist Name} {Song Title} {CD-ID} The above is displayed only if the user had previously selected videos. Click Here If You Would Like To Change Your Karaoke Song Selection! button is exposed here, for the user to indicate they want karaoke songs. If clicked, proceed to Page 4.
Purchase If anything is selected, a button is displayed here. If clicked, proceed to Page 5.
Page 3: Video Entry Page Page 3: Text Displayed
(Welcome Message Here), {Name} {Similar to Page 1} {Name} is the name that was entered on page 1.
Your CD Is Now (x%) Full This shows running gauge showing how much of the CD is Full, based on previous selections. When the CD is 100% Full, no entries below may be offered selected.
Please Select The Video You Want From The Following List. The following post is sent to the server
http://{server}/karaoke.txt?query=?VIDEO?USER={URL SAFE USERNAME} or http://{server}/karaoke.txt?query=?VIDEO ?TICKET_VENUEID=12345678_TICKETPURP=01_TICKETID=00000002
The significance of the numbers in red bold is: Digits 3 through 10 on the User ID Ticket
The significance of the numbers in blue bold is: Digits 1 through 2 on the User ID Ticket
The significance of the numbers in purple bold is: Digits 11 through 18 on the User ID Ticket
The Data Returned will be the following:
VIDEOQUERY :
RES : 2 SONG : ARTIST: Mike - FIRST Time Singing! TITLE : You Might Think VIDEOURL : http://{path}/{filename}.nsv INDEX : 2 HASH : 2323299893 {random data} SONG : ARTIST: Mike - 2nd Time Singing! TITLE : American Idiot VIDEOURL : http://{path}/{filename}.nsv INDEX : 3 HASH : 4329874237 {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.
If RES is 0, do not display this page at all, instead display "You Have No Videos", wait 5 seconds, then go back Page 2
Otherwise...
A table is displayed here with the previous search results. If this is the first time the page is displayed, this section is omitted. The columns are as follows:
Artist Title {Artist Name} {Title Name} {Artist Name} {Title Name} {Artist Name} {Title Name}
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.
The user may individually select any of the above songs, and has a quick way to select all songs.
As users select songs, the CD gauge increases until the CD is full. When the CD is full, no entries should be permitted to be selected.
If the user selects a song, remember all data for the given song, and proceed to Page 2. Page 4: Song Entry and Search Page Page 4: Text Displayed
(Welcome Message Here), {Name} {Similar to Page 1} {Name} is the name that was entered on page 1.
Your CD Is Now (x%) Full This shows running gauge showing how much of the CD is Full, based on previous selections. When the CD is 100% Full, no entries below may be offered selected.
If You Know the CD-ID, Enter That Here: text box is exposed here, 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=%3FALBUM+%3D%3D+%22158%22+AND+TRACKNO+%3D%3D+%2211%22
The significance of this post is a query for CD-ID 158-11. 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 SONGURL : http://{path}/{filename}.zip {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.
Please Select Your Song From The Following List. A table is displayed here with the previous search results. If this is the first time the page is displayed, this section is omitted. The columns are as follows:
- indicates a song that was queued or sung earlier
Artist Title Sung? CD-ID {Artist Name} {Title Name} * {xxx-yy} {Artist Name} {Title Name} * {Artist Name} {Title Name} *
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.
As users select songs, the CD gauge increases until the CD is full. When the CD is full, no entries should be permitted to be selected.
If the user selects a song, remember all data from the selected song, and proceed to Page 2.
To Search Songs For Artist Or Title, Enter Search Text Here: A text box is exposed here, for the user to enter a search term. 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}
Example: 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. Page 5: Acknowledgement Page Page 5 is shown when the user confirms the selections.
At this point, the files are downloaded from the server, using the SONGURL and VIDEOURL values that were collected from the previous entries.
The Videos need to be converted into VCD format, the SONGS into CD-G format.
Note a customer who purchases videos will also get the Karaoke Songs that they sung in their video as CD-G.
Page 5: Text Displayed:
Thank You, {Name}.
Your CD is Now Being Produced, and will be ready in approximately xx Minutes
After 5 seconds, the Terminal Program proceeds to Page 1.
