

                 DigitalCD v2.42,  Andr Timmermans 1996-1999


Required external applications


+ Rick Hudson's Play It 1.57 should be installed on your system be able to play WAV files and other sample files.

+ DigitalCD will be able to talk to John Beranek's Acorn CDDB application (version 0.19) provided that you configure the CDs section in the choices window correctly. For those who don't know, CDDB stands for CD DataBase and is a way for you to avoid typing the description of each of your CDs. John's client CDDB application will endeed read the characteristics of the CD in your drive and contact one of the CDDB servers on the net in order to retrieve its description.

Introduction


DigitalCD is a desktop music player compatible with RISC OS 3.1 or later (including StrongARM). It provides independent control panels for any connected CD drive and music files playlists.

To play a music file, open the 'Music Files' control panel from the icon bar menu or click SELECT on the icon bar, then drop the file to play on it. Music files currently supported are: Digital Symphonies (&10B), Protrackers and ArcTrackers (&CB6), Matrix (&00B), ScreamTrackers (&C02), FastTrackers (&C03), ImpulseTrackers (&C04), Multi Tracker Modules (no known filetype) and MPEG Audio (&1AD) including those with variable bitrates.

To create a playlist, select 'Playlists' from the icon bar menu. From the Playlists window menu select 'New', an empty playlist will appear. Finally, drop the files to play on it, or even better, drop a directory on it, all the supported music files in it and subdirectories will be added to the playlist. To play files from the playlist, set the 'Music Files' control panel in Program mode and start playing.

To play a CD, open the corresponding control panel from the icon bar menu or in the case of CD drive 0 click ADJUST on the icon bar.

DigitalCD supports interactive help. To make use of this feature, load the Help application supplied with your computer, or an alternative Help provider such as Bubble Help. Making use of this feature (which works on menus as well) should help you to work out what everything does if you can't guess.

I have tried to render the program as straightforward as possible in use and I have put as much information as possible in the interactive help, so use it! If you still have questions, then read the rest of this help file and should you encounter real troubles, try the troubleshooting section near the end of the file.


The Control Panels


Here follows a description of a control panel from top to bottom and from left to right (on the default skin). Nearly all of the commands are also available
from the control panels menu.

1) The Title Bar contains two lines of text. The first one will display, when relevant, the author and title of the track list. The second one displays the title of the current track.

2) The Track Counter shows the track that is currently played. Clicking on the counter will open a list from which a new track can be chosen.

3) The Timer has four available modes: elapsed time, remaining time, total elapsed time and total remaining time. The first two modes refer to timings within the current track, while the second two refer to timings for the whole list of tracks. Clicking SELECT or ADJUST on the timer will allow you to cycle within the four modes.

When are playing music files the timer will only display a pseudo time based on the current pattern and event. I did it because it was easier for me to use the same code for CDs and music files, but in the end it's a good thing. First, important changes in the music often occur on the start of a new pattern, so with a pattern display you start to expect these changes. Next, according to playing speed changes and other subtle effects, you will experience that time is relative and that sometimes you can even travel back in time. ;-)

4) The Position Bar is a graphical representation of the current position within the track. You can click on the bar to move to a given position within the track.

5) The Volume Slider will allow you to alter the loudness of the played tracks by dragging it up or down.

Important Note:
When playing music files you can also edit the properties of the track and specify a volume in percents of this main volume. I can only recommend you set the main volume to an adequate value, then for each track in the playlist only alter the relative volume. This will ensure that once the playlist is saved you will not need anymore to fiddle with the volume slider on each track change.

6) The Mode Switches alters the way tracks are played. By clicking with SELECT or ADJUST, you can cycle within the possible values of each of the following switches:

+ Repeat has four modes:

  - play track list,
  - loop on track list,
  - loop on current track and
  - play a single track (useful when you think:
    Ok, It's nearly time to leave,
    I will stop when this one is played).

+ Intro scan:
when set, will only play the start of the tracks, allowing you to search a given track. The time spend on each track can be altered from within the choices window.

+ Shuffle:
when set, will play the tracks in random order.

+ Program:
when set, will play the tracks which belongs to the preference list of the current CD or the tracks from a music files playlist.

7) The Custom Area

The content his section depends on the type of player.

For a CD player there is a single icon that opens the CD Database window.

For the Music file player four icons are shown to:

+ remove the current track from the playlist,
+ delete (after confirmation) the music file corresponding to the current track,
+ edit the properties of the current track or
+ open the current playlist.

8) The Main Buttons

+ Play allows you to:
  - start playback,
  - restart the current track or
  - resume playback on a paused track.

+ Pause allows you to:
  - pause playback or
  - resume playback on a paused track.

+ Stop allows you to stop playback.

9) The Move Buttons

+ Rewind allows you to move back within the current track,
+ Forward allows you to move forward within the current track,
+ Previous allows you to move to the previous track and
+ Next allows you to move to the next track.

10) Window icons

In addition to the usual 'back' and 'close' icons you will find:

+ the 'pin' icon to iconise the window
+ the 'minimise' icon to turn control panel into a mini-bar.

Keyboard operations:
--------------------

Space/Return      Play/Pause
Esc               Stop

Left Arrow        Rewind
Right Arrow       Forward
Shift + Left      Restart track
Ctrl + Left       Previous
Ctrl + Right      Next

Ctrl + Up         Main Volume up fine
Ctrl + Down       Main Volume down fine
Ctrl + Page Up    Main Volume up
Ctrl + Page Down  Main Volume down

I                 Switch Introscan On/Off
P                 Switch Program On/Off
R, Shift + R      Cycles through Repeat modes
S                 Switch Shuffle On/Off
T, Shift + T      Cycles Timer modes

CDs:
Ctrl + Insert     Open CD database

Music files:
Up Arrow          Track Volume up fine
Down Arrow        Track Volume down fine
Page Up           Track Volume up
Page Down         Track Volume down

Insert            Track Properties
Ctrl + Insert     Open Playlist
Delete            Remove Track from playlist
Ctrl + Delete     Delete Track file
Ctrl + K          Start plug-in
Ctrl + Shift + K  Stop plug-ins


The Music Files Properties window


This window lets you to define a volume scale relative to the main volume in the control panel. The output volume is then applied with the following formula: min(100%, main volume * scale), which means scales above 100% will only have an effect if the main volume is lower than 100%. For those without powerful speakers I would recommend to put the main volume to 100%: first find the quietest song in their playlist leave it with the scale 100% and downscale the other songs.


The Music Files Playlist windows


On top of the window you will find from left to right the usual content of a save box: icon for dragging, filename entry box and save button. 

Below the icons you will find a list of music files, this is where you will have to drop the files or directories you want to play. The list can be managed either by the mouse or by the keyboard.

Mouse operations:
-----------------

Click with ADJUST on the window if the window does not have the focus, will set the focus to the last item which owned the focus.

Click/drag with SELECT on an deselected item will clear any previous selection and start the selection of a range of items.

Click/drag with ADJUST will preserve the current selection and invert the selection status of a range of items.

Click/drag with SELECT on a selected item will start dragging the current selection. You will be able to drag the selection to a filer, another application, the 'Playlists' window where it will create a new playlist, this playlist where a ghost caret will show you the destination of your move (copy if shift is pressed), or another playlist where a ghost caret will show you the destination of your copy (move if shift is pressed).

Click with ADJUST on a list which as not the focus sets the focus to that list without altering the current selection.

Several additional commands are provided by clicking MENU on the list:

+ Validate will remove from the list any file which have an invalid path. This is useful for removing deleted files from the list.

+ Properties will allow you to edit the properties of the currently selected item.

+ Delete Files will allow you to remove the currently selected items from the playlist and delete (after confirmation) the corresponding files.

+ Standard Cut, Copy and Paste commands (Global Clipboard is supported).

+ Select All and Clear commands.

Keyboard operations:
--------------------

Usual actions on [shift][ctrl] arrow, page up, page down

- Ctrl + A selects all items
- Ctrl + Z clears all items
- Ctrl + C copy the selection to the clipboard
- Ctrl + V inserts the clipboard content before item which has the focus
- Ctrl + X copy the selection to the clipboard, then deletes the selection
- Del deletes the selection (no use of the clipboard)

- Ins toggles follow mode on/off (use the arrows and you will understand).
- Shift + Ins starts/ends a selection of an area.
- Ctrl + Ins starts/ends an inversion of an area.

- F3 Save file.

Playlist File Format:
---------------------

The file format is purely textual and can be edited by hand if required (e.g. you moved your files to another drive or directory).

To keep file sizes as small as possible a mechanism of current path is used and the following algorithm is used to read the file:

cur_path = ""
while more lines to read
  read line
  if line is dot terminated (line is a path)
    cur_path = line
  else (line is in format <file> or <file>*<options>)
    filename = cur_path + file
    if (options section)
      fileoptions = options
    else
      fileoptions = default options
    endif
  endif
endwhile

options has the following format:
<name>=<value>,...,<name>=<value>

but currently the only one defined is:
v=relative volume in %

File example:
ADFS::HardDisc4.$.MultiMedia.Sound.Symphony.Songs.A.
Anette*v=250
ANewJack


The Playlists window


This window allows you to manage playlists: from this window you can create a new playlist, remove existing playlists (closing the playlist window does not remove the document from memory, it only hides it from view) and finally choose the playlist from which the 'Music Files' control panel will extract the files to play.


The CD Database


DigitalCD stores the identifier (the one returned by WhichDisc) of each CD it plays. From this window you can browse through the identifiers and assign the name of an author and a title to the CD and to each track of the CD. Note that the whole CD information can be typed without the need to use a single mouse press: pressing Return will move the caret to the end of the next writable icon of the dialog box and for the last track icon increase the track number and move to the end of the first track icon.

A Preference List window can also be opened to define an alternative sequence for playing the tracks of the CD.


The Preference List


The preference list window is used to define an alternative sequence for playing the tracks of a CD. This sequence will be used when the CD control panel is in Program mode.

The window contains two list: on the left the preference list and on the right the list of tracks available on the CD.

From the right list you can select tracks and drop them at the desired position in the preference list.

From the preference list you can move/copy/delete tracks, clear the list or initialise it to reflect the list of available tracks. The tracks in this list can be mixed in any order and any track may inserted several times in the list.

Your changes will only be taken into account when the Save button is pressed in the CD Database window.


Choices


Changes in this window will not take effect until validated by clicking either on the Save or Set icons. Well, not true really since all sound effects are applied in real time, however they will revert to their original settings it you click on Cancel or close the dialog box.

1) Players options

+ Skins provide alternative look and feel for the control panels and mini-bars of DigitalCD. To change the skin used by DigitalCD select another one from the list.

To create your own skins for DigitalCD, read the file !DigitalCD.Docs.Skins which will provide you the necessary information.

+ Intro scan length is the number of seconds players configured in Intro Scan mode will play a track before moving to the next track. The default is 15 secs.

+ Stop playing on error forces the player to stop after a loading error instead of skipping to the next track. It's very useful when all the files in your playlist are zipped and you forgot to start SparkFS.

2) Startup options

+ Restore open windows will ensure that DigitalCD stores the position of open windows before quitting the application so that when the application is restarted these windows will be reopened at the position where you leaved them.

+ Load playlist allows DigitalCD to load a default playlist at startup (unless the application is started by double clicking on a playlist). To specify the filename of the default playlist, type its name in the entry box or drop its icon onto it.

+ Start playing tells DigitalCD to immediately start playing from the last played position in the previous DigitalCD session.

3) Files options

+ Use filename as track title will prevent DigitalCD from using the title of the music files in the playlists and in the player title bar. Instead the leafname of the file will be used.

+ Unload module at track exit will force DigitalCD to remove the RMA module used to play the track when that track is ended.

The list at the bottom of the window shows the filetypes loaded by DigitalCD and the name of the module used to play each of them. Have a look at the section 'Accepted FileTypes' below if you desire to modify that list.

4) CDs

4.1) CDFS

+ CDFS version with 150 frames bug

On some versions of CDFS (or CDFSSoftAtapi?) there is a bug in the code which is responsible for a 150 frames (2 seconds) difference between the value you specify to the CD interface to move to a given position on the disc and the value returned when asking the current position on the CD.

Is the problem present on your machine? Well, start playing a CD and use the Rewind and Forward buttons they should normally move you 1 second backward or forward in the track. If you experience something as the Forward button moving you backward in the track, turn the switch on.

+ Play CD track by track is my old method for playing CDs and detecting track changes. The new method avoid the small pauses that occurred between two tracks but seems to fail on some CD drives so it is still available for compatibility
(normally fixed since v2.38).

+ The polling delay is the minimal time interval between to position/status checks in CD control panels. If you find that playing CDs slows down your desktop too much, increase this value.

4.2) CDDB

+ CDDB tells if DigitalCD must attempt to ask Acorn CDDB about CDs for which it has no desciption.

+ Allow remote connection tells CDDB that he may connect to external servers to attempt to find CD descriptions which are not stored in its local database.

+ Show query status provides a visual clue that requests to CDDB are taking place.

+ CDDB path should contain the path of Acorn CDDB on your machine so that it may start the application in case its not running yet. To fill the entry box just drop the !CDDB icon onto it.

5) Mixing

+ The Mixing Frequency is the rate at which the players feeds the sound hardware with sound sample information. Using a higher frequency will provide a better sound quality but will also consume more processing power (except for MP3 files). Owners of 16-bit cards will be able to select from the complete frequency list provided by the card but these will be mapped to the nearest 8-bit frequency list for player modules without 16-bit support.

+ Set Interpolation to perform a linear interpolation between the values of samples (the output becomes less metallic). On non-SA machines turning it off could save some valuable processing power.

+ Volume ramping: instead of jumping from one note volume to the other, the player will use a short volume ramp at the start of every frame, which will remove some of the pops and clicks in the sound.

+ The Balance slider can be used to offset the sound to the left or the right.

+ The Stereo Separation slider is used to modify the separation between the left and right channels. You may want to decrease it with headphones, or increase it for a more spatial sound. You can even invert the stereo.

6) Equalizer

This option is only available while using the TimPlayer and DiskSample modules and requires that your machine is fitted with a StrongARM. To use it just tick the Equalizer settings and while playing adjust the amplification sliders of each frequency band.

Once you are pleased with a set of settings just enter it's name in the writable icon and press the Save button below that field. The set is now saved and will appear in the menu associate to the popup icon at the right of the writable icon. You are now free to experiment different set of settings and save the best ones. To recall a saved set just select it from the menu.

To delete an unwanted set type it's name in the writable field (or select it from the menu) and press the Delete button.

7) Iconbar

This window defines which player windows are opened by clicking on the iconbar icon, just choose from the list the player with Select and Adjust.

8) Plug-Ins

Plug-Ins provide full screen or windowed (desktop) music driven animations. Until new hardware permits to monitor CD drives sound output, plug-ins are not available for CD control panels.

To change the plug-in used by DigitalCD select another one from the list and push the Setup button to configure it.

When the option 'Auto start with song' is active DigitalCD will start the plug-in automatically for you when playing a first track.

To create your own plug-ins for DigitalCD, read the file !DigitalCD.Docs.Plug-Ins which will provide you the necessary information.


Accepted FileTypes


Inside the !DigitalCD directory you will find a file called Setup and in this file a section [FileTypes]. On startup the application scans this section for lines in the form:

filetype = loader1, loader2, ...

where filetype is a RISC OS filetype, loader1 the first player that will attempt to play the file, loader2 the second one if the first refuses, etc.

For example CB6 = tim, qtm tells DigitalCD to accept filetype CB6 and play such files with the TimPlayer module, or with QTM if TimPlayer refuses.

For a complete list of loaders, see just below in the Credits.


Credits


Thanks to the authors of the following modules/applications:

ds     DSymphonyPlayer 1.46  BASS 1991-1997, Freeware
qtm    QTMTracker      1.27  Phoenix/QUANTUM
trk    matrixTRK       0.89  Marko Lukat & Michael Pohle
xpr    XprMod          1.10  Skoe of Expression
tim    TimPlayer       0.91  Timmermans Andr
smp    DiskSample      0.11  Timmermans Andr
       + AudioMPEG     0.10  Peter Teichmann
playit PlayIt          1.57  Rick Hudson
                              http://www.actrix.gen.nz/users/rick/
       DCDUtils        0.14  Timmermans Andr
       Acorn CDDB      0.19  John Beranek
                              http://www.acorn.com/~jberanek/cddb/



Legal stuff


This program is 'Freeware' and must not be copied to make a profit. This means that individuals, Public Domain libraries and Disc magazines may distribute DigitalCD as long as they charge no more than required by the distribution costs (disc, postage, ...).

You may not distribute modified versions of this program and the program must be distributed as a whole. You are not allowed to use bits of it in your own programs without asking my permission (or in case of the modules the author of the module).

This program is supplied as is, and no liability can be accepted for damage or loss resulting from the use or misuse of the software.


Contacts


The latest version is available on the web at:

http://www.geocities.com/SiliconValley/Horizon/4471/

If you want to contact me, my e-mail address is:

  Andre.Timmermans@sbs.be

and this is my snail-mail address:

  Timmermans Andr
  Rue du Vert Coron, 17
  7600 Pruwelz
  Belgium



                                Troubleshooting


1) The CD player skips track 1 or skips tracks when using the Rewind/Forward buttons.

Stop playing the CD and open the Choices window. Move to the CDs section, invert the state of the 'version with 150 frames bug' option, validate by clicking on the Save or Set button and restart CD playing. For the few persons for which the solution is known not to work, I am afraid I still in the dark.

2) When listening to music files the player sometimes interrupts for no apparent reason the current file and plays to the next file.

There are several possible reasons here:

+ You just used Ctrl+Left, Ctrl+Right or some other keyboard shortcut while the player's control panel still had the focus. If you find these shortcuts irritating, you can disable them by deselecting 'Allow shortcuts' in the 'Misc' section of the control panels' menu.

+ The song contains an end of sequence marker or a jump to a backward position in the pattern sequence. The last patterns in the sequence are either trials discarded from the final version or the file is composed of several songs probably for a game (Lemmings springs to my mind). If you wishes to listen to that section of the file, switch repeat mode to loop on track and while playing use the Rewind/Forward buttons to move to that part of the file.

3) I am unable to save the CD information I just typed in.

The most probable causes are that you have write protected the file !DigitalCD.CDs, you are running !DigitalCD from a write protected archive (beware also that !SparkFS 1.33 or earlier gets into trouble when attempting to write to a read only archive) or are running !DigitalCD from a read only file system or media (such as a CD).


                                    History


2.00 01 Dec 96 First release ready version (but never released)
2.01 06 Jan 97 Correction of play button behaviour when track is playing
               or paused
2.02 18 Jan 97 Correction, F12 in list does not work
2.03 09 Feb 97 Faster memory deallocation through wimp slot shrinking on
               Wimp_Poll only
2.04 21 Feb 97 Rewrite of selection dragging in Lists
2.05 04 Apr 97 Rewrite of CD driver to minimise CD SWI calls
               (due to "Tool - Undertow")
2.06 19 Apr 97 Introduced support for QTM player, storage of Volume info
2.07 20 Apr 97 Alpha support of multiple playlists
2.08 21 Apr 97 Choices: Update button status after dragging of a play list
2.09 03 May 97 Rewrite saving methods and handling of dragging
2.10 17 May 97 Added menu on playlists; volume could not be dragged to 100%
2.11 25 May 97 Completed support for multiple playlists
2.12 28 May 97 Now perform dragging in CD Preference List as for other lists
2.13 23 Jun 97 Introduced new icons in player, redesigned other ones
2.14 24 Jun 97 Support for removal of current track from playlist
2.15 25 Jun 97 Support for deletion of file corresponding to current track
2.16 05 Jul 97 Alpha support for track volume in % in main volume
2.17 14 Jul 97 Edition of track volume in % added
2.18 20 Jul 97 Corrected edition of track volume
2.19 27 Jul 97 Corrected long standing random crash on exit
2.20 03 Aug 97 Redesigned playlist windows, much smaller now.
2.21 10 Aug 97 Changed a few details, messages and wrote 80% of the help file
2.22 19 Sep 97 Removed usage of RiscOSLib, got official filetype allocation
2.23 03 Oct 97 Inserted timer to check less often CD position
2.24 04 Oct 97 Extended Playlists limits from 999 to 9999 files
2.25 29 Oct 97 Included XprMod to support S3M (&C02) and XM (&C03) songs
2.26 15 Nov 97 Menu separators used a gray background
2.27 14 Jan 98 Included TimPlayer module and added Setup file to define
               the list of accepted filetypes
2.28 02 Feb 98 Fixed bug in position bar when adding/removing files
               from the list
2.29 19 Apr 98 File filtering routine for playlist was broken by Setup file code
2.30 04 May 98 Tuned CD routines so that for contiguous tracks are
               not interrupted
               Corrected some the ids of some help messages
               Corrected bug in menus on pre-RPC machines
2.31 18 May 98 Play files double-clicked or dropped to icon bar as if dropped
               on the control panel window (turns program off)
2.32 08 Jun 98 Redesigned the Choices window
               Added 'Stereo Pairs', 'Interpolation' and 'Start playing' options
2.33 15 Jul 98 My change in 2.30 for CD routines doesn't work on at least one
               drive so Added the 'Play track by track option' to select the old
               method.
2.34 22 Jul 98 Finished support of mini-bars and skins.
2.35 26 Jul 98 New version of TimPlayer with modified SWIs.
2.36 02 Oct 98 Dynamic loading of skins
     07 Oct 98 Choices file read and written using Choices$Path & Choices$Write
     13 Oct 98 Added keyboard shortcuts for control panel
     04 Nov 98 Redesigned Choices to cope with new TimPlayer options.
     04 Dec 98 Updated help file and messages.
2.37 15 Dec 98 Some buttons don't work after skin changes.
     30 Dec 98 Support for visualisation plug-ins.
     02 Jan 99 Snap control panels to screen limits and icon bar.
     15 Jan 99 Playlist menus didn't work correctly after skin changes.
     24 Jan 99 Introduced minimal CD polling interval,
               reduced polling of closed window.
     07 Feb 99 Added menus on control panels.
2.38 26 Feb 99 CD panel: toggle between disc info and track author every 5 secs
     08 Mar 99 Bug fix in CD play routine which caused on some drives DigitalCD
               to play correctly only in 'track by track' mode (with only
               troubles on the last track).
     10 Mar 99 Iconbar action is now configurable.
2.39 16 Mar 99 Removed an annoying CD access when quitting DigitalCD.
     20 Mar 99 Allow full-screen plug-ins key forwarding even when player
               has disabled keyboard shortcuts.
     25 Mar 99 Support for MP3 files starts now.
     04 Apr 99 Redesigned mixing configuration, the visible change being that
               mixing frequency replaces the mixing quality.
2.40 22 Apr 99 Wait till we are sure AudioMPEG_Info returns something
2.41 01 May 99 Rewrote saving of settings, much faster
     07 May 99 Corrected bug with CD Extras
     11 May 99 Added option not to unload player modules when song finishes
     23 May 99 Added 'Auto start' option for plug-ins.
     08 Jun 99 Added File Type vs Module info in choices window.
     18 Jun 99 Equalizer support
     19 Jun 99 Equalizer styles support
     27 Jun 99 Removed a few bugs that should make it work on RISC OS 4.0
2.42 23 Jul 99 Skin stuff extended for more compatible WinAmp skins
     24 Jul 99 CDDB support
     24 Jul 99 Sorted .1 sec shorter duration showed sometimes by AC3Train/MPG
     15 Aug 99 I am bored to acknowledge the loading errors of each file in the
               playlist when I forget to load !SparkFS, so I added an option
               to stop playing after the error instead of skipping to the next
               track.
     16 Aug 99 CD did not stop anymore in play single mode with option 'play CD
               track by track' unticked
     16 Aug 99 Forgot to set Equalizer at the start of new MP3 files (when
               unload module option was ticked).
     05 Sep 99 Split author and title in CDDB info, access CDDB only if no title
               is defined yet.
     23 Sep 99 Little change to avoid Euro char used as tick on RISC OS 4.