Installation, Notes and FAQ

$Revision: 1.20 $

$Date: 2005/01/04 02:50:05 $

1. Overview
   • What is Jan's DEC Web Control?
   • What is new?
   • iRadio advanced decweb control
   • Logging of decweb commands
   • Native DEC Database reading
   • Potential for CRON Control and other customizations
   • How it works - what is unique about this one
   • Visual Demonstration - screen shots
   • Default index_decweb.html page
   • iRadio DecWeb Page (Regular Browser)
   • iRadio interactions (Regular Browser)
   • PDA (iPAQ) pIE browser View (tailored for PDA screen/functionality)
   • Dec Engine View (Regular Browser)
   • Music Selection View (Regular Browser)
   • Music Selection using Regular Expression View (Regular Browser)
   • Playlist Edit Interaction View (Regular Browser)
   • Playlist Name Edit Interaction View (Regular Browser)
2. Installation and Basic Configuration
   • Assumptions and Dependencies
   • Get the decweb distribution
   • What is included in the distribution
   • Installation Steps
   • Getting started
     • Point the browser and GO
     • Dry run using the distributed music db
     • Initialization of the decweb music db using Your music library
     • Full power to the decweb NOW
     • DecWeb Configuration File
   • Debugging
3. Web Navigation - browser view
   • DEC Direct Control
   • Selection from Music Library
     • Artist Album Track pulldown menus
     • Default pulldown menu content
     • Regular Expression Search
   • Playlist Management
     • Adding to Playlist
     • Deleting from a playlist
     • Updating Playlist back to the DEC
4. Implementation Details
   • CGI Parameters
     • General Rules of CGI Parameters
   • DEC Command Engine
     • Dec Command Structure
     • DEC native commands (remote control)
     • DEC extended commands (predefined)
     • DEC dynamically generated commands
     • Commands from file
     • Page(Down | Up) optimization
   • Music Selection
   • Debugging
5. File Formats and sample
   • DEC Web generated File Formats
   • DEC Listing Files (DEC Export Files)
   • Music and Playlist files
   • Playlist Dynamic Edit files (temp)
6. TO DO list
   • Known Bugs
   • Enhancements

The New Additional Features

The following are the major new features:

• iRadio web interface to allow selecting, searching and playing dec iRadio stations.
• direct reading of the dec database rather than relying on th dec export files. however, only the iRadio is sourced from these new decfiles, for backward compatibility.
• logging of the actual dec commands allowing for further extensions such as cron, and/or execution via command line, in batch.

  iRadio advanced decweb control

  see the screen shots for iRadio DecWeb Page (Regular Browser) and iRadio interactions (Regular Browser)

  Logging of decweb commands

  notice that there is now a log directory that will capture every decweb command set sent to the dec via the web interface, nice for debugging and visibility what it does in the background. the location should be /usr/local/apache/htdocs/decweb/logs directory. you can also access that via the browser at http://your-ip-or-dec-name/decweb/logs/

  
  Sun Jan  2 18:22:13 2005 actdec.pl -attr=all -dec=m:d-2:s:u-3:s:b:s:d-3:s:b:s:d-0:p
  Sun Jan  2 18:23:31 2005 actdec.pl -attr=all -dec=m:d-2:s:u-3:s:b:s:d-4:s:b:s:d-29:p
  Sun Jan  2 18:40:49 2005 actdec.pl -attr=all -dec=m:d:s-3:d-68:s:d-0:s:d-0:s:p
  

  Native DEC Database reading

  perl script db_read.pl will read and dump the content of your database and generates all the decweb files. it logs its progress/result into the logging directory. you should see something like this as a result of db read.

  
  querying DEC database ...
      artists: 248
      tracks: 4375
      albums: 335
      genre: 43
      playlist items: 825
      playlists: 99
      radio entry items: 575
      radio category definition: 29
      radio category xref: 720
      radio favorites: 4
  db query finished 16.630 seconds
  creating decweb files ...
      sorting artists albums per dec specification ...
      artists.txt ...
      albums.txt ...
      tracks.txt and all.txt ...
      playlists_header.txt ...
      playlists.txt ...
      radio.txt ...
      radio_category.txt ...
      radio_favorites.txt ...
  done [/usr/local/apache/htdocs/musicdb/] 4.430 seconds
  

  Potential for CRON Control and other customizations

  you can see exactly what is the decweb engine command sequence by visiting the log file, see Logging of decweb commands and then you can put these commands into a script and/or directly into the cron schedule. for example, see a selection in the log file and issue the command from the command line, ie

  actdec.pl -attr=all -dec=m:d-2:s:u-3:s:b:s:d-4:s:b:s:d-29:p
  

  and it will play it. obviously, you can then put these commands into a cron and have your favorite radio station, album, artist, song wake you up at the same time every morning ....

  another opportunity is to schedule the dumping of the database to go with your update of your radio stations, so you don't have to do it manually. just execute the /usr/local/apache/cgi-bin/db_read.pl script and off you go.

  What is Jan's DEC Web Control?

  HP DEC is aka digital entertainment center. more information see Lee's website The concept of web control is not new for the DEC. my implementation is based on phil's works. i noticed that dave also developed extensions to the original web interface by phil. for more details see Lee's development website.

  jan's implementation of web interface adds the following to the original concepts already explored:

• dec press command engine via the web

  defines and implements a dec engine that accepts any sequence of DEC's press commands. the DEC engine executes the submitted commands and displays the X image after it is done. so any sequence of commands that you would issue from a remote or front panel controls is possible through this web interface. yes, i piped 100 commands to the dec through the web and watch the tv screen dance :) the other operations implemented by this web interface, such as music library selection of artist, album, track and playlist as well as the edits of the playlists is eventually brought back to the dec via this dec engine.

• artist, album, track and playlist music selection

  web interface to select artist, album and track in form of menu pull downs and table listing allows you to access your entire music library via the goofiness of web interactions. it also allows to regular expression search through your music library. any music library selection can be either played on the DEC and/or added to a playlist

• playlist creation via add/delete edits as well as changing its name

  web interface to add and/or delete items from your playlist. the item could be artist (all albums) or album or individual track (song). also web interface to perform playlist name change. the playlist edits are sent back to the dec via the dec press command engine and the web interface synchronizes with the dec's new internal definitions of playlists.

  How it works - what is unique about this implementation

  simply this is what happens behind the scene: the reading of the the dec is based on the dec's exported listing files of the music library content. so on one side this web interface generates the dec listings and reads the dec's music library content from the exported files. when the play music selection and/or playlist edits are done via the web a cgi script translates the requested dec action into the appropriate sequence of the simple press dec commands. if edits were performed it the web interface auto synch with the latest dec's internal view of the music library including the playlists.

  Assumptions and Dependencies

  in order to run this web interface you need to first install apache server on your dec. follow the instructions on Lee's development website. the cgi scripts as well as the dec library listing files parser are implemented in perl. i used the perl version available on the dec, so no extra perl packages are required. although the web interactions can be hosted on any server, assuming that you can remotely execute the press commands and grab the exported dec listing files and the display xdump from the dec somehow, i implemented everything on the dec web server, for good or ill. note: the decweb engine has also a file interface so changing the cgi based decweb engine to a simple deamon that can read the commands piped to it via a named pipe file and a simple samba share to communicate with the requestor (presuming cgi based on another web server). the share would be used to get dec press commands in (using the file named pipe interface) and grab exported listings as well as the dumped X image on the established share. so the requirement of having a web apache server running directly on the dec itself can be eliminated.

  httpd configuration (all of these are done by default, so if you have not changed a thing, you should be ok) all of these notes assume that you have installed (auto by default) the apache in the default directory ie: /usr/local/apache. also it is assumed that the following user identification User nobody and Group nobody for cgi-bin scripting using the User and Group tags. if you are unsure check the httpd.conf file in the /usr/local/apache/conf directory.

  Visual Demonstration - screen shots

  A sample of screen shots were assembled. the PDA view using pIE browser with simplified interface and functionality is included. also the regular size screen of a desktop/laptop was utilized.

  Get the decweb distribution

  obtain the distribution from here select the desired version/package. the package is in RPM format. allowing both initial as well as upgrade process. the rpm package includes a set of (cgi and non-cgi) scripts, a set of the dec web music files in order to allow more controlled setup and experience. also this help documentation (this document) is included in the distribution.

  Installation (or Upgrade) Steps

  move the RPM package to /tmp directory on your dec. (if desired, to make things easier follow instructions how to samba share your apache home directory and/or tmp directory from your dec in Debugging section) once the distribution is in the right spot unpack it following these instructions: assuming that you are logged onto your dec as a root most likely using telnet session.

  • first go to the /tmp directory

    
    			cd /tmp
    	

  • for illustration i assume that the distribution is called decweb-2-7.i686.rpm
  • you can first verify the content by running the following command

    
    			rpm -qvilp decweb-2-7.i686.rpm
    	

    see the discussion about what is included in the distribution
  • if all looks good, now you can install it onto your dec.

    
    			rpm -i decweb-2-7.i686.rpm
    	

  • if you are upgrading the package (previously installed) use the following command

    
    			rpm -U decweb-2-7.i686.rpm
    	

  • setting the (sticky bit) permissions for press and xwd commands by executing the following commands

    
    chmod 4755 /usr/X11R6/bin/xwd
    chmod 4755 /opt/odin/dec/bin/press
    so you should see something like this
    -rwsr-xr-x    1 root     root        37513 Mar 26  2002 press*
    	

  • there is no need to perform any special browser configuration, since the images captured from the dec root console, virtual that is, are stored in the directory

    htdocs/deccontrol/screen

    and are named using the unique process id. if you use the image based interface a lot, you may want to periodically clean up the htdocs/deccontrol/screen directory and get rid of all the *.jpg files.
  • it appears that the DEC File sharing setting has to be enabled in order to be able to export the dec database content. in spite the fact that the files are not accessed over the network, it appears that it has be enabled (unconfirmed) here is how you enable the setting: on the DEC cascade through the menu (default menu structure) home->settings->network settings->advanced network settings and ensure that it is enabled. if not toggle the value of this setting in order to enable it.

  What is included in the distribution?

  • the cgi-bin and other scripts
  • a sample db in the htdocs/musiclist directory (to conduct the dry run test if desired) only for the initial installation this sample db will NOT ever be updated in your subsequent upgrades; therefore, protecting your own database from being trashed. (labeled as RPM config files)
  • this help.html in the htdocs/decweb directory (labeled as RPM documentation>
  • index_decweb.html in the htdocs directory
  • the remote.gif and sample screeshot.jpg in the htdocs/deccontrol directory

  Point the browser and GO

  point your browser to http://your-dec-ip-address/index_decweb.html or http://your-dec-host-name/index_decweb.html

  if you have your own index.html file you may want to simply import/copy the content of the index_decweb.html default index file.

  Dry run using the distributed music db (init pckg only)

  if you installed the package for the first time rpm -i *.rpm that includes a sample of the decweb music files you can test out decweb before you actually initialize the decweb's internal db files with the content of your dec's music library. you can still browse through the music selection and playlist edits pages (using the content of the distribution). it is a good test to see if all is working before you make the next step. however, do NOT play any of the music selections or DO NOT commit any update of the playlist edits back to the dec. there is no harm per say, however you will not see the results you want to see. if you want to play/edits music selections or playlistsi you need to first initialize your the decweb database. if you feel comfortable you can skip this step of testings and move to the next step of initializatin right away.

  Initialization of the decweb music db using Your music library

  this covers the very first time you initilize the decweb music and playlist db. there are 3 ways to do it. i recommend that you use the 3d alternative (manual) only if you experience difficulties using alternative 1 or 2. you can also run the script manually (3rd method), just to see if you have any inconsistency issues in your music library.

  if you are using the default index_decweb.html file you can generate the iRadio files via the web by clicking on the Read and Dump Native DEC DB button. that will generate the decweb intermediate files from the database. they should be stored in the /usr/local/apache/htdocs/musicdb you should see something like:

  
  -rw-r--r-- 1 nobody nobody 14625 Jan 2 17:42 albums.txt
  -rw-r--r-- 1 nobody nobody 819777 Jan 2 17:43 all.txt
  -rw-r--r-- 1 nobody nobody 8914 Jan 2 17:42 artists.txt
  -rw-r--r-- 1 nobody nobody 147905 Jan 2 17:43 playlists.txt
  -rw-r--r-- 1 nobody nobody 2832 Jan 2 17:43 playlists_header.txt
  -rw-r--r-- 1 nobody nobody 30986 Jan 2 17:43 radio.txt
  -rw-r--r-- 1 nobody nobody 1025 Jan 2 17:43 radio_category.txt
  -rw-r--r-- 1 nobody nobody 106 Jan 2 17:43 radio_favorites.txt
  -rw-r--r-- 1 nobody nobody 678719 Jan 2 17:43 tracks.txt
  

  for more details Native DEC Database reading

  after you generated the files you can go back via the browser button. again once index_decweb.html page and click on the iRadio DecWeb control and off you go :). you will notice that there are now 2 pages that are linked to hop via a button between music selection and the iRadio page. you should be able to get to the radio via the standard advanced music selection page. details here are the ways to initialize the decweb database (assuming that you are using the default index page index_decweb.html)

  1. invoke the DECWeb Initialization and Control button in the first page.
  2. first invoke the DECWeb control (Traditional) button. then when you see the image of the control and captured Xdump of the DEC Screen you can proceed by by clicking the hp symbol on the remote control in the first page.

     either of these methods will do the following: create the dec exported listings as well parse out these files and generates the decweb music library. note: you may need to do it twice, if you have not ever exported listings files before. the reason is that the listing generation process checks for a changing size of one of the exported file, so the first time it may complain that the file doesn't exist.

  3. more manual, yet more control on what is happening process is split into 2 steps.
     • first generate the dec music listing by using the standard menu approach. using the web remote control go to the music library and down to create listings and execute
     • once the listing are generated you can manually execute the following script

        
       /usr/local/apache/cgi-bin/gen_musiclist.pl
       		

       you should see one line statistics about processed files if you have any issues you may see warnings about the consistency of your music library content.

  Full power to the decweb NOW

  after you have initilize the decweb internal database, you can do what ever you want. note: any playlist edits commited back to the dec will automatically generate the decweb music library content. however, when you perform any edits on your music library (outside of the decweb) you need to synch up the decweb content using the hp logo on the decweb's remote.

  Debugging

  first define a samba share for the apache server and/or temp directory, so you can easily edit using a real editor, remotely and also see the results accumulated in the httpd log files. add the following to the samba share configuration file in /etc/smb.conf

  
  [apache]
  comment = apache directory
  path = /usr/local/apache
  read only = No
  guest ok = Yes
  guest account = nobody
  
  [tmp]
  comment = temp directory
  path = /tmp
  read only = No
  guest ok = Yes
  guest account = root
  

  when you exhaust the understanding about what the apache server log file error.log in the logs directory accumulated (depending how your apache is configured, the cgi scripts should add warnings and fatal messages to the log). you can also increase verbosity of debugging of the scripts themselves. first ensure that the first line in the script reads #!/usr/bin/perl -w all the scripts have an additional debug flag included. simply set the $debugFlag = 1; in the any of the cgi-script warning: the debug echo statements will most likely mess up the appearance of the page pretty bad since they will be interpreted as an html. even though all debug print statements are enclosed by the PRE html tags. to really see the unclobbered content, you should view the generated html code by a cgi-script including the debug statements using the browser View->Source.

  DecWeb Configuration File

  A config file config.txt is available in the cgi-bin subdirectory. this file allows reasonable configuration without hacking the code. be careful, all the existing entries are required, there is no provision of defaults provided in the code. so edit with absolute care.

  if your menu on your dec has been altered, that's when you want to edit this file to define your menu items structure. you may want to send the command sequence to the dec manually first, before you edit this config file.

  A separate config_music_dec_menu.txt is also available (contributed by reymond). This config file works with the menu changes some people performed on their decs in order to view images/pictures. if you would like to use this file instead, just rename the file to config.txt and all should be ok.

  consult dec CGI parameter table for details how to use the file interface to the command interpreter. to send command manually just edit the tempd/fname file and invoke the cgi script with ?attr=file parameter. for example http://your-dec-address/cgi-bin/actdec.cgi?attr=file will read a default command file in the default temp directory most likely /tmp/dec_commands.txt. every time you refresh the page with the address, the content of the file will be read and sent to the dec.

  anyway, here is a sample config file

  
  # $Header: /data/cvs/dec/htdocs/decweb/help.html,v 1.20 2005/01/04 02:50:05 jkrucky Exp $
  # decweb configuration file, PARAM | VALUE pairs
  # white spaces are ignored
  # menu mapping
  listing | stop:m:d:s:d-5:s-2
  artist  | m:d:s-3
  playlist| stop:m:d:s:d:s:b:s
  album   | m:d:s-2:d:s
  music   | m:d:s-2
  library | m:d:s
  iradio  | m:d-2:s
  favorite|m:d-2:s:u-2:s:b:s
  browseradio|m:d-2:s:u-3:s:b:s
  cd      | m:s
  # general configuration parameters
  timeout | 15
  music_list_max | 600
  pl_max | 700
  

  DEC Direct Control

  	click	dec press cmd	decweb code	description
  	a	n/a	n/a	go to music selection page
  	b	refresh	refresh	refresh dec's view
  	c	nowplaying	np	show what is playing
  	d	n/a	m:s	cd selection
  	e	n/a	m:d:s	music library
  	f	n/a	m:d-2:s	iRadio view
  	g	n/a	m:d:s-3	artist view
  	h	menu	m	home (menu)
  	i	add	a	add
  	j	time	t	shuffle / repeat
  	k	info	i	info
  	l	options	o	options
  	m	back	b	back
  	n	up	u	up
  	o	pgup	pu	page up
  	p	left	l	left
  	q	select	s	select
  	r	right	r	right
  	s	down	d	down
  	t	pgdn	pd	page down
  	u	rew	rew	rewind
  	v	play	p	play
  	w	fwd	f	forward
  	x	record	rec	record
  	y	stop	stop	stop
  	z	pause	pause	pause
  	hp	n/a	n/a	generates dec listings and creates decweb db files timeout is set to 15 seconds
  	n/a	guide	g	guide
  	n/a	display	dis	display
  	n/a	eject	e	eject
  	n/a	n/a	m:d:s-2	music
  	n/a	n/a	m:d:s-2:d:s	album

  Selection from Music Library

  all the discusions about pulldown menus is also applicable to the html table listing. in other words, you can use either approach to get to the music listing you desire. the pulldown are alphabetically sorted, while the html table is positionally sorted. also, for each element (artist, album, track, playlist) in the html table listing you can press the play link that will play the selection without leaving the webpage.

  the pulldown and the html table contents are synchronized, so if you either click on the title (in the html table) or select from a pulldown you will achieve the same result.

  the native dec listings are positionally important, meaning that for example the second item in artist, album, track file is indeed the second item in the corresponding screen. so the selection of that artist, album, track is faked by blindly pressing the virtual remote down button twice. this positional info is encoded into the index of an element. see more details about the structure of the decweb music file formats.

  there are two important concepts regarding the pulldown menus (and the html table full listing). the first one is the content of the pulldown and the second one is the selection wihin the content.

  • pulldown content: gets populated either by default selection criteria or by regular expression search.
  • pulldown selection: find and select an item from the content by using
    • scrollbar of the pulldown menu
    • typing a letter when in the pulldown will get you quickly to the first item that starts with that letter
    • use down/up/pgdown/pgup keys to browse through the pulldown content
  the default population is achieved by listing the first N items available in the category (artist, album, track). see default pulldown content discussion

  Artist Album Track pulldown menus

  all music selection pulldown menus get synchronized every time any of them is selected. for example

  • select artist -> will populate only albums and tracks for that artist
  • select artist and then album -> will populate only tracks on that album
  • select album -> will populate only tracks on that album and selects the album artist
  • select track -> will populate only the album and select the correct artist
  • reset music selection -> will invoke the default population of the pulldown menus

  Default pulldown menu content

  when no special search criteria (regular expression search) is given, the first (top) N items in the category is used to populate the pulldown. currently the limit N is set to 200. see discussion about the musicselection script

  Regular Expression Search

  type in a regular expression to search through the artist or album or track db to populate the content of the pulldown menu first. for example

  • john.* will find all items starting with john, John, JOhn, JOHn, JOHN, jOhn etc
  • .*john.* will find all items with word john (+ upper case permuts) in them
  • .*n$ will find all items ending on a letter n or N
  the regular expression search is case insensitive. this RE is used in context of the command grep. some special symbols such as ^ may not work as expected because the typed in RE is a part of an overall RE used for the file search.

  Playlist Management (Name and Content)

  only non-empty playlists are exported from the dec. however, in addition, you should always see 5 more empty playlists in the pulldown menu. this allows creation of a playlist from scratch using the decweb interface (added by the gen_musiclist.pl script). note: the labels of these additional empty playlist are using the dec's default naming convention. so if you changed a name of a playlist on the dec and the playlist is empty at the time of the latest export, it still doesn't get exported.

  you should not use the browser's back and forward buttons, when managing playlist. otherwise you may add multiple instances of playlist's adds. use the button on the page instead to go to music selection page.

  Adding to Playlist

  you always have to select a playlist from the pulldown (or the html page) first before you can operate on it (add/view/delete). when the button add to PL is clicked, the current music selection is added to the selected playlist. don't worry if you click the button multiple times. only one instance of a music selection will be added. if only artist is selected, all albums and tracks will be added. if artist, album is added all the tracks will be added. any music selection is valid and can be added and exists as an independent additional entity. therefore, if you add artist and album and then also add a single track from the same artist/album. you will have the track there twice, one by the selection of artist, album and one fully qualified of artist, album, track

  the playlist html table includes the number of items already commited to DEC as well as the number of edits still pending (add and deletes)

  Deleting from a playlist

  you can delete either a track from the original dec's listing. or you can delete some (or all) of the items that were just added (before applied back to the dec)

  Updating Playlist back to the DEC

  all the edits (deletes first followed by adds) are sent to the dec. the deletes of the adds are cancelled out and will not be sent to the dec. once the dec is updated the view of the playlist should represent exactly what the dec has internally. note: unfortunately, if you add entire album, commit to the dec, then you will be able to delete only by the individual tracks (rather than by the original addition - entire album)

  CGI Parameters

  actdec.cgi
  variable	value	description	default
  attr	direct decweb command or listings or all or file or playl or pedit	execute the decweb command	attr=refresh
  fname	file name to read comands from ( tempd/fname is actual location)	if attr=file use fname to obtain commands	dec_commands.txt
  dec	the : separated set of dec commands	if attr=all or attr=playlexecute decweb command if attr=pedit execute command and generate listings	n/a
  sel	what was the last music selection	to pass back what we got (remember to selection within the pulldowns)	n/a
  playl	what was the last playlist selection	to pass back what we got (remember to selection within the pulldowns)	n/a
  tempd	temp directory to be used	temp directory	/tmp

  musiclist.cgi
  variable	value	description	default
  attr	music selection in format A:B:C	current music selection to be operated on. actions such as play add to PL will be invoked for the current music selection used to pre-select from the pulldown menu items	attr=0:0:0
  targ	regular expression search argument	artist album track	track
  q	regular expression query search string	use for RE search	n/a
  pact	playlist action	keep erase none	keep
  playl	playlist selection	to pass back what we got (remember to selection within the pulldowns)	0:0
  tempd	temp directory to be used	temp directory	/tmp

  playlist.cgi
  variable	value	description	default
  attr	music selection in format A:B:C	just remember so it can be passed back to the music selection web page	attr=0:0:0
  playl	playlist selection	to pass back what we got (remember to selection within the pulldowns)	0:0
  tempd	temp directory to be used	temp directory	/tmp
  del	assumed active selection of playl then the track selection to be deleted	add the deletion to the del temp file (if ^0.* then erase all deletes for the playlist)	n/a

  General Format of CGI Parameters

  standard cgi parameter list of variable=value pairs separated by the & symbol is used.

  DEC Command Engine

  Dec Command Structure

  any a native dec command, the press command, listed in dec command table can be sent to the dec. the structure of the command is press command name-repeat count where the -repeat count is a optional. by default, all commands sent to the dec without the -repeat count suffix will be translated to -1, meaning repeat of count 1. when repeat count is 0 the command will be ignored. a set of commands separated by : will be parsed out and applied sequentially as individual commands. so here is an example m:s-2:d-2:s:p will result in the following sequence:

  menu select select down down select play

  some checking is performed on the commands (their validity) before they are sent to the dec engine. so if you send an undefined command, it will be skipped. there is no functional difference between s-3 and s:s:s

  DEC dynamically generated commands

  the music selection and the playlist management cgi scripts generate a sequence of the commands to be sent to the dec when one the buttons play music selection, play playlist or update dec playlist is pressed

  Commands from file

  also a set of commands can be specified in a file. the structure of the file is simple:
  • all EOL (unix \n) are translated to the command separator :
  • comment lines starting on the symbol # are ignored
  here is an example of a command file

  
  # this get to the menu
  m
  # followed by 12 down, select, play, refresh
  d-12:s:p:refresh
  # that's it for the command file
  

  Page(Down | Up) optimization

  pagedown is equal to 6 downs. so d-13 will be executed as pd-2:d-1. the same for the up commands. just to limit the number of commands send to the dec.

  Music Selection

  a pulldown content is generated by using grep -i regular-expression on the appropriate decweb music db file (artist or album or track). then within the content the appropriate selection is found (if any is given). the reason why using the system grep first is that there may be virtually thousands of entries and only relatively small subset is pertinent. the regular-expressioncombines searching on the index or the name within the file

  DEC Web generated File Formats

  DEC Listing Files (DEC Export Files)

  i think there is a discussion about the dec export listings files on lee's website.

  DEC WebMusic and Playlist files

  general structure of these is using an index followed by a number of fields such as name. the symbol | is used as a separator, unix text formatting expected. the music list files index is in form of A:B:C. the subindex fields (A, B, C) are 1 based (0 means don't care). A is for artist, B for album and C for track. the playlist files use two level of index (ie A:B) where A is the index within playlists and B an index for the tracks for that playlist. the order of items within these files is pretty much unimportant. the key to the dec insight information is the index
  example preview of all files used:

  
  artists.txt decweb file
  10:0:0|Big Head Todd and the Monsters
  11:0:0|Bjork
  
  albums.txt decweb file
  10:1:0|Another Mayberry
  10:2:0|Midnight Radio
  10:3:0|Sister Sweetly
  11:1:0|Debut
  
  tracks.txt decwebfile
  10:1:10|Waiting In America
  10:1:11|Hymn
  10:2:10|City On Fire
  10:2:11|Monument In Green
  10:2:12|Ann Arbor Grandfather
  10:3:10|Circle
  10:3:11|Brother John
  10:3:1|Broken Hearted Savior
  11:1:10|Violently Happy
  11:1:11|The Anchor Song
  
  all.txt decweb file
  10:1:10|Big Head Todd and the Monsters|Another Mayberry|Waiting In America
  10:1:11|Big Head Todd and the Monsters|Another Mayberry|Hymn
  10:1:1|Big Head Todd and the Monsters|Another Mayberry|Flander's Fields
  10:1:2|Big Head Todd and the Monsters|Another Mayberry|Another Mayberry
  
  playlists_header.txt decweb file
  1:0|Playlist #1|17
  2:0|Playlist #2 (empty)|0
  
  playlists.txt decweb file
  1:1|Blues Traveler|Blues Traveler|Alone
  1:2|David Gray|White Ladder|My Oh My
  1:3|Fleetwood Mac|Fleetwood Mac|Warm Ways
  1:4|R.E.M.|Out Of Time|Losing My Religion
  1:5|The Rolling Stones|Tattoo you|Waiting On A Friend
  1:6|Various Artists|Shrek Soundtrack|Rufus Wainwright / Hallelujah
  1:7|Ben Harper|Fight For Your Mind|Gold to Me
  1:8|Bob Dylan|Bob Dylan's Greatest Hits|I Want You
  1:9|Bruce Springsteen and the E St|Live 1975-1985 disc 1|Fire
  1:10|Eric Clapton|Unplugged|Running On Faith
  1:11|Lou Reed|New York|Dirty Blvd.
  1:12|The The|45RPM|This is the Day
  1:13|The Beatles|Sgt. Pepper's Lonely Hearts Cl|Lucy in the Sky with Diamonds
  1:14|Bryan Ferry|Boys And Girls|Slave To Love
  1:15|John Lennon|Lennon Legend|Jealous Guy
  1:16|Norah Jones|Come Away With Me|Come Away With Me
  

  the direct reading of the database resulted in new extended information available.

  ==> albums.txt <==
  2:1:0|Shooba dooba|15|15|0:54:45|15
  3:1:0|Gold Greatest Hits|17|17|1:17:03|19
  180:1:0|Jackie Brown|18|18|0:50:59|17
  7:1:0|Oremi|19|19|0:47:48|12
  8:1:0|Dilate|20|20|1:00:19|11
  
  ==> all.txt <==
  2:1:1|-123 min.|Shooba dooba|Illusion|179|15|Rock|02:40|2.56|2002/11/23-12:11:01|/content/music/slurped//-123 min/Shooba dooba/01-Illusion.mp3
  
  2:1:2|-123 min.|Shooba dooba|Tilagetcha|180|15|Rock|04:36|4.43|2002/11/23-12:13:21|/content/music/slurped//-123 min/Shooba dooba/02-Tilagetcha.mp3
  
  2:1:3|-123 min.|Shooba dooba|Play, my finger|181|15|Rock|03:25|3.29|2002/11/23-12:15:05|/content/music/slurped//-123 min/Shooba dooba/03-Play, my finger.mp3
  
  ==> artists.txt <==
  2:0:0|-123 min.|15|0:54:45|15
  1:0:0|10,000 Maniacs|143|0:43:06|11
  231:0:0|<>|211|0:00:41|1
  3:0:0|ABBA|17|1:17:03|19
  4:0:0|Alabama|254|0:48:36|10
  
  ==> playlists.txt <==
  1:1|Simon and Garfunkel|The Concert In Central Park|Homeward Bound|1847|140|Unknown Genre|04:22|6.30|2002/12/21-20:31:34|/content/music/slurped//Simon and Garfunkel/The Concert In Central Park/02-Homeward Bound.mp3
  
  1:2|Sublime|Sublime|What I got|1982|153|Reggae|02:51|4.11|2003/03/15-21:57:34|/content/music/slurped//Sublime/Sublime/02-What I got.mp3
  
  1:3|The The|45RPM|This is the Day|2212|166|Avantgarde|03:58|5.72|2003/01/01-19:39:34|/content/music/slurped//The The/45RPM/11-This is the Day.mp3
  
  ==> playlists_header.txt <==
  1:0|amy's adieu|16|1:12:13
  2:0|Playlist #2|29|1:59:51
  3:0|Unknown ? stuff|4|0:15:53
  4:0|misc (czech)|4|0:17:30
  5:0|elevator music (dinner)|15|1:05:51
  
  ==> radio.txt <==
  19:1:0|Bigupradio.com (128)|0|00:00:00|0
  19:2:0|BoomboxRadio - Ska (28)|0|00:00:00|0
  19:3:0|CKLN - 88.1 FM (28)|0|00:00:00|0
  19:4:0|KVRX - 91.7 FM (28)|0|00:00:00|0
  19:5:0|RASTAMUSIC.COM (32)|0|00:00:00|0
  
  ==> radio_category.txt <==
  19:0:0|Reggae/Ska [6]|6|00:00:00|6
  7:0:0|Country [12]|12|00:00:00|12
  15:0:0|Oldies [15]|15|00:00:00|15
  8:0:0|Dance/Techno [36]|36|00:00:00|36
  16:0:0|Pop [49]|49|00:00:00|49
  
  ==> radio_favorites.txt <==
  1:0|[WXDU - 103.5 FM (96)]
  2:0|[HOBER Radio (96)]
  3:0|[WGFS Covington, GA (56)]
  4:0|[KEXP - 90.3 FM (56)]
  
  ==> tracks.txt <==
  2:1:1|Illusion|179|15|Rock|02:40|2.56|2002/11/23-12:11:01|/content/music/slurped//-123 min/Shooba dooba/01-Illusion.mp3
  2:1:2|Tilagetcha|180|15|Rock|04:36|4.43|2002/11/23-12:13:21|/content/music/slurped//-123 min/Shooba dooba/02-Tilagetcha.mp3
  2:1:3|Play, my finger|181|15|Rock|03:25|3.29|2002/11/23-12:15:05|/content/music/slurped//-123 min/Shooba dooba/03-Play, my finger.mp3
  2:1:4|Tutti-frutti in realtime|182|15|Rock|04:12|4.05|2002/11/23-12:17:13|/content/music/slurped//-123 min/Shooba dooba/04-Tutti-frutti in realtime.mp3
  2:1:5|Hookered|174|15|Rock|04:22|4.20|2002/11/23-12:19:24|/content/music/slurped//-123 min/Shooba dooba/05-Hookered.mp3
  

  Playlist Dynamic Edit files (temp)

  in the temp directory, these files store all the web interactions regarding to playlists. one hosts the additions and the other one deletions. the structure of these files is similiar using playlist index (in form of A:B where A is the playlist and B is the track) and additional music selection index to be added.

  
  playlist_add.txt decweb temp file
  1:0|12:3:11|a
  1:0|13:0:0|a
  1:0|14:1:0|a
  1:0|14:2:0|a
  3:0|14:3:1|a
  4:0|14:3:2|a
  
  playlist_del.txt decweb temp file
  1:11|del
  1:12|del
  1:14:1:0|del
  1:14:2:0|del
  3:14:3:1|del
  
  

  all playlist updates are deleted/cleared after the edits have been committed to the dec.

  Known Bugs

  • initial hesitation (fixed?) - it appeared that if dec is inactive for a while, it will drop the first command. implemented suggested by lee, of sending 'refresh' command when in screensaver mode (bumps process)

  Enhancements

  • use the direct decweb database to obtain more information, namely the length of individual items. obsolete the dependency on the decweb file listings.
  • optimization of traversing through the artist or playlist lists on the dec. currently it only goes down but because there is circular notion: the time (# of commands issued) may be further reduced for the bottom half of the lists.
  • the default population of the pull down menus. currently the top is only displayed. allow bottom approach as well. this is specially important for the tracks, where potentially thousands could be displayed. however you can control that with a regular expression
  • pre-process the RE in the form, allow ^ character to be useful.
  • playlist listing supress printing when name (artist, album) is the same as the item above it.
  • when playlist is updated to the DEC all edits to other playlist that were not commited to the dec are lost. allow erasing only for the playlist tha is updated. making this persistent for the entire session.
  • cron clean up of the httpd log files and screen image directory
  • alarm set a playlist to start playing at specified time
  • add genre to the search music selection web site
  • playlist sorting, use a numerical subsort when # is in the name of the playlist
  • hide the RE search as an optional item
  • add cool graphics to the webpages. implement a traditional looking jukebox:)
  • allow re-numbering of the items in the playlist.
  • the temp files are not unique per process/session. concurrent use of different browser sessions may clobber the temp edits on playlist. allow a session specific temp dir.
  • synch up the format of the temp_add and temp_del files. they should follow the same style of the indexing
  • better trapping of errors, allow a monitor window.
  • add the mp3 streaming discussed on lee's website. so the requestor can actualy hear the action
  • when updating the playlist do not stop playing.
  • when updating the playlist start playing it
  • clear entire playlist (on the dec not one by one) clear command

  ---

  email author (jan) with any issues or suggestions

  REV: $Header: /data/cvs/dec/htdocs/decweb/help.html,v 1.20 2005/01/04 02:50:05 jkrucky Exp $