                                   DigitalCD
                                   

                         Version 3.16, 21 December 2023
  
   Introduction

   Players:                   Playlists:            
     CD player                 Main playlist      
     File player               File queue         
     Internet radio player     Secondary playlists
     Sound monitor             Directory lists    
   Control panels               Imported lists     
                                Yellow pages       
                                                    
   CD database                Choices (sections)    
  
   Resource management:
     Accepted filetypes
     Skins
     Visualisation plug-ins

   Required external applications

   List   Tree view   Troubleshooting

   Table of Contents   Index   Licence   Credits   History
  
                                                 Freeware,  Andr Timmermans 


                                   Introduction
                                   

    DigitalCD is a desktop music player compatible with RISC OS 3.1 or later.
    It provides independent players for CDs, internet radio stations and
    music files, and a sound monitor.

    You should start by reading about players, control panels and playlists.

    After this, instructions for using the four DigitalCD players are at the
    following links:

       CD player
       Music file player
       Internet radio player
       Sound monitor

    DigitalCD's other features include skins, visualisation plug-ins, a CD
    database and more. The choices window allows you to configure every
    aspect of DigitalCD. If you encounter any problems with the program,
    don't forget to check the troubleshooting section.

    DigitalCD supports interactive help. To make use of this feature, load
    the Help application supplied with your computer, or use an alternative
    such as BubbleHelp or Float. The interactive help provides quick
    explanations for all of DigitalCD's functions.


                             Introduction: Playing a CD
                             

      To play a CD, open the DigitalCD icon bar menu, and choose the player
      for the drive you wish to use from the Players submenu. The control
      panel for this drive will then be displayed. Insert the CD in the drive
      and wait until it has been detected. This will be apparent because the
      'CD drive is empty' message will be replaced with new information.
      Click Play to start playing the CD. If program mode is off, the tracks
      will be played in the same order as on the CD. If program mode is on,
      the tracks will be played in the order you set in your preference list.
      For further details on the CD player window, see the control panel
      documentation.

      The CD database allows you to store information about the CD, such as
      its title, artist, and the track titles. You can type the information
      in by hand, or use AcornCD to obtain the data from the internet.

      Note

      Some CD drives do not work properly under RISC OS, but there are
      workarounds for most of the problems that arise. If you have problems
      playing CDs, please refer to the troubleshooting section of this manual.


                         Introduction: Playing music files
                         

      To play music files, first open the DigitalCD icon bar menu and choose
      either Main playlist or File queue. 

      A playlist will appear, initially empty. Drag and drop one or more
      music file or directory icons onto the playlist to add them to the
      playlist. If you drag a directory icon, all music files contained in
      that directory and any of its subdirectories will be added. 

      The first and most forward difference between the two playlists is that
      the contents of the main playlist is automatically saved on exit of
      DigitalCD while the content of the file queue is strictly temporary and
      will be lost on exit.

      To play files from the playlist, open the DigitalCD icon bar menu and
      choose Music file player from the Players submenu. The control panel
      for this player is shown and you need to make sure that the program
      mode is set to play tracks from the correct playlist: active for the
      main playlist and inactive for the file queue.

      Click the Play button to start. For further information, see the
      control panel documentation.

      The following links describe playlist management and controlling track
      playing order in greater detail.


                      Introduction: Playing an Internet radio
                      

      DigitalCD supports internet radio. Internet radio stations use audio
      streams to broadcast their data. DigitalCD supports MP3 or Ogg Vorbis
      HTTP streams, but not AAC, WMA or other formats. However, your machine
      and DigitalCD must be suitably configured before you can listen to
      these stations. You need to have an updated MimeMap file, and you will
      need to configure DigitalCD with details of your internet proxy
      settings, if any. See prerequisites for further details.

      To add new internet radio stations:

      1)  Open the DigitalCD icon bar menu and choose Main playlist.

      2)  Ensure that your machine is connected to the internet.

      3)  Start a web browser and look for internet radio lists. (These are
          widely known as .m3u or .pls files). For beginners, two useful
          starting points are Winamp (http://www.winamp.com/music/) for MP3
          radio stations and the Icecast directory (http://dir.xiph.org/) for
          Ogg Vorbis stations.

      4)  Download some of the proposed lists and drop them onto the main
          playlist. DigitalCD will then add entries to the main playlist for
          each radio URL contained within the file. Some files may add more
          than one station when dropped onto the playlist. The different
          stations will usually carry the same content but at varying
          bitrates.

      To play internet radio:

      1)  Open the DigitalCD icon bar menu and choose Internet radio player
          from the Players submenu. The control panel for this player will
          then be displayed.

      2)  Click on the Play button to start. To select a different station,
          open the control panel's menu and select the station you want from
          the Play submenu. See the control panel documentation for further
          information.

      In case of problems, see the troubleshooting Internet access section in
      this manual.


                                     Players
                                     

    DigitalCD provides several players, listed in the Players submenu of the
    DigitalCD icon bar menu. Each player has its own control panel. Players
    are designed to play lists of objects called tracks and to provide
    information on each track as it is played. The types of objects that can
    be handled depend on the player. For example, the music file player can
    play a wide variety of sound formats including MP3s, tracker files and
    sound samples, while the CD player plays audio CDs.

       A CD player allows you to play audio tracks from CDs. If you have
        multiple CD drives, each can have its own player, numbered after the
        CD drive number shown on the left of the icon bar (':0', ':1', etc.).
        Information on the CD, including its title, artist, and track titles
        can be entered into a CD database, either by hand or by using AcornCD
        to obtain this information from the internet. Finally, you can set up
        preference lists to control the order in which CD tracks are played,
        to repeat tracks, and/or to skip CD tracks you don't like.

       The music file player handles files from a wide variety of different
        filetypes. When the file player is in program mode, it plays tracks
        from the file queue. Otherwise it plays tracks from the main
        playlist. The following link gives further details on how tracks are
        managed.

       The internet radio player allows you to listen to internet radio
        stations. These stations are managed from the main playlist.

       The sound monitor allows you to treat the output of any sound sampler
        known to DigitalCD as if it was a music track. Playing tracks from
        the sound monitor allows you to use DigitalCD's visualisation
        plug-ins on sounds produced by sources other than DigitalCD itself,
        including other music applications and even external sources such as
        a microphone.

    The sounds handled by any of DigitalCD's players can be visualised
    on-screen using plug-ins. However, DigitalCD must have an appropriate
    sampler to capture the sound from its source. This does mean that CD
    music cannot normally be displayed via a plug-in, unless you have
    additional sound sampling hardware.


                                     CD player
                                     

      DigitalCD has control panels for playing CDs.

      If you are new to DigitalCD, please start by referring to playing a CD.

         Track list and playing order
         CD(s) properties
         CD track(s) properties
         CD database

         Troubleshooting


                       CD player: Track list and playing order
                       

        Which tracks the CD player plays depends on the selected program mode.

               When program mode is inactive, the player will simply use all
               the audio tracks on the CD from start to end.

               If program mode is active and a preference list has been
               defined for the CD, the CD player will use that list instead.
               A preference list allows you to change the playing order for
               the CD, miss tracks out entirely, or repeat them.

        If shuffle mode is active, the tracks from the list will be ordered
        randomly before being played.


                               CD player: CD properties
                               

             To open the CD properties window select one or more references
             CDs in CD database and either:
                Shift+double-click on those references,
                click on the properties button of the playlist's toolbar,
                choose Properties from the CD database's menu.

        The simultaneous edition of the properties of several CDs restricts
        the range of editable properties. The properties which differ from
        one track to another will be displayed in a different colour.

        This window allows you to:
           alter the name of the album to which the CD belongs.
           alter the release date of the album, in format YYYY, YYYY-MM or
            YYYY-MM-DD.
           alter the name of the set to which the album belongs.
           alter the name of artist to which the album belongs.
           alter the name of collective to which the artist belongs.
           open the preference list window which allows you to define an
            alternative playing sequence for the tracks on a CD. You can
            change the playing order, repeat tracks, or leave them out
            entirely.


                               CD player: Preference list
                               

          The preference list window allows you to control which tracks are
          played from a CD, and the order in which they are played. The
          preference list is used when the CD control panel is in program
          mode.

          The window contains two columns: the currently-defined preference
          list is on the left, and the list of tracks available on the CD is
          on the right.

          You can select tracks from the right-hand list and insert them into
          the preference list.

          To help speed up data entry, the Initialise button can be used to
          erase the current preference list, if any, and copy the entire
          'Available tracks' list into the preference window. The Remove all
          button clears the preference list. <= Insert and Remove => allow
          you to move tracks into or out from the preference list. You can
          select multiple tracks and add or remove them all in a single
          operation.

          CD tracks can be omitted entirely from a preference list, or
          inserted more than once. Note that if the preference list for a CD
          is completely empty, then all tracks from the CD will be played
          normally regardless of whether program mode is active or not.

          All operations on the preference list can be performed using the
          window buttons, the menus, the keyboard or by drag and drop.


                            CD player: CD track properties
                            

             To open the CD track properties window select one or more
             references to tracks in the CD database and either:
                Shift+double-click on those references,
                click on the properties button of the CD database's toolbar,
                choose Properties from the CD database's menu.

        The simultaneous edition of the properties of several tracks
        restricts the range of editable properties. The properties which
        differ from one track to another will be displayed in a different
        colour.

        This window allows you to:
                alter the title of the track.
                alter the name of artist to which the track belongs.
                alter the name of collective to which the artist belongs.


                                    File player
                                    

      DigitalCD uses the music file player control panel to play files
      containing music.

      If you are new to DigitalCD, please start by referring to playing music
      files.

         Track list and playing order
         Accepted filetypes.
         File properties
         Metadata and metadata extractors

         Troubleshooting


                      File player: Track list and playing order
                      

        The music file player's list of tracks depends on the program mode.

               When program mode is active, the player will play the content
               of the file queue.

               When program mode is inactive, the player will use the main
               playlist instead. Only references preceded by a ticked
               checkbox are considered:

                  File references are simply added to the track list.
                  Unloaded playlists and directory lists are ignored.
                  The content of loaded playlists and directory lists are
                   examined, and only file references preceded by a ticked
                   checkbox are added to the track list.

        The Files section of the Choices window allows you to control
        DigitalCD's behaviour when files are dropped onto a control panel or
        the DigitalCD icon bar icon. You can set DigitalCD to add files to
        the main playlist or the file queue, and you can also configure
        DigitalCD to select the appropriate program mode and immediately
        start playing the file.

        The order in which tracks are played is controlled by the shuffle
        mode. Tracks can be arranged in various ways:

           Tracks can be grouped at several levels: collective, artist,
            album set, album.
           Tracks from compilation albums follow the same level grouping
            order as normal albums unless compilation is selected.
            In that case the level grouping order becomes album set, album,
            followed by collective, artist if by artist is selected.
           Groups can be shuffled or sorted alphabetically at each level of
            grouping.

        Within the defined groups, tracks may be:
           Shuffled.
           Sorted alphabetically.
           Following the album order (album grouping must be active).


                              Files: Accepted filetypes
                              

        DigitalCD can play all the file formats listed below, assuming they
        have been associated with the expected RISC OS filetypes. The list of
        filetypes and formats can also be further customised if needed.
        Additional configuration options allow you to:

           Cause DigitalCD to, automatically load itself and play the file,
            when a given filetype is double-clicked.
           Add extra filetypes supported by newer versions of decoders such
            as PlayIt.
           Add alternative filetypes sometimes used for some formats (e.g.
            MODs from Krisalis games with filetype &CC5).
           Change the decoder used to play a given filetype when more than
            one choice is available (e.g. MP3 files can be assigned to
            AMPlayer or DiskSample).
           Provide a list, by order of preference, of decoders used to play
            a given filetype (e.g. some WAVE files containing MP3 are
            playable with DiskSample, while most other WAVE file variants are
            unsupported and should be passed down to PlayIt).

        If you regularly use the internet to download files or if you
        exchange files with platforms other than RISC OS, I strongly advise
        you to keep an up-to-date MimeMap file containing the associations
        between internet MIME types, RISC OS filetypes and PC/Mac file
        extensions.

            Supported file formats   Extension RISC OS filetype

            Trackers
            MatrixTRK     00B
            Digital Symphony        10B
            ImpulseTracker .it  1AE 
            FastTracker 2  .xm  1AF 
            ScreamTracker  .stm 1B0
            ScreamTracker 3     .s3m 1B0 
            Asylum    .amf 1B1
            DSMI AMF  .amf 1B1
            Composer 669   .669 1B1
            Digi Booster   .digi     1B1
            DigiBooster Pro     .dbm 1B1
            DigiSound .dsm 1B1
            DSIK .dsm 1B1
            Digital Tracker     .dtm 1B1 
            Farandole Composer  .far 1B1
            MultiTracker   .mtm 1B1
            Oktalizer .okta     1B1
            PolyTracker    .ptm 1B1
            UltraTracker   .ult 1B1
            Coconizer     365
            Archimedes Tracker      CB6
            Desktop Tracker         CB6
            Protracker     .mod CB6
            Soundtracker   .mod CB6
            The Xperience  .mod CB6

            Lossy compression
            Ogg Vorbis     .ogg 1A8
            MPEG Audio Layer 2  .mp2 1AD
            MPEG Audio Layer 3  .mp3 1AD
            AAC (ADTS)     .aac A62
            AAC (MP4) .m4a A62

            Lossless compression
            Free Lossless Audio Codec (FLAC)   .flac     1CF
            Monkey's Audio (APE)     .ape 1F0
            ALAC (MP4)     .m4a A62

            Uncompressed
            CDAudio       0CD
            DataVox       108
            Digital Symphony Sample      10A
            AmigaIFF      693
            ARMovie       AE7
            AudioWorks         BD6
            Armadeus      DC3
            RawSound      ED0
            Creative Voice .voc F96
            Sun Audio .au .snd  FB1
            Wave .wav FB1
            AIFF     FC3

            Others
            MIDI .mid FD4 

           These formats were previously listed with unofficial filetypes
            from The XPerience demo group's well-known alternative icon set.
            However, there were some clashes with official filetype
            allocations, so the clashing entries have now been assigned
            official filetypes of their own.

           There is another unsupported file format with the same file
            extension.

           These files are played through the MIDIPlay module. The MIDIPlay
            module doesn't decode the sound by itself, but redirects the MIDI
            commands to a MIDI synthesiser. MIDI synthesis is not provided by
            default on RISC OS machines, but Liquid Silicon sells both the
            Synth software MIDI synthesizer and MIDI hardware that could be
            used.


                        Files: Accepted filetypes, configuration
                        

          Filetypes list

              Inside the !DCDRes directory you will find a file called Setup
              (Click here to open), and in this file a section [FileTypes].
              During the boot or startup DigitalCD scans this section for
              lines in the form:

              filetype = loader1, loader2, ...

              where filetype is a RISC OS filetype, loader1 is the first
              driver that will attempt to play the file, loader2 is the
              second if the first one refuses, and so on.

              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.

              With the notable exception of its own files or type FileList
              (RISC OS type 155), DigitalCD will only accept to load files
              with a type listed in this section. You may add, modify or even
              suppress at will these mappings between filetypes and drivers
              as you can always check the reference version located in the
              directory !DigitalCD.Copy.

              For a complete list of drivers, refer to the Credits section.
              To that list you have to add the driver smpext, a variant of
              smp which attempts to use the file name extension (like "/mpeg"
              of "/ac3") to identify the type of file to play.

          DigitalCD as default application for a given filetype

              In the list of filetypes, put a "!" in front of the filetypes
              you wishes DigitalCD to be started when you double-click on a
              file of this type. DigitalCD must of course have been seen by
              the desktop (booted) for this to work.

          New versions of DigitalCD

              !DCDRes.Setup is your private version of the setup file and
              DigitalCD will never try to modify it. It could therefore be
              wise to check with each new version of DigitalCD if
              modifications haven't been made in the default list of
              filetypes proposed in !DigitalCD.Copy.Setup.


                                  Files: Properties
                                  

             To open the Files properties window select one or more
             references to files in a playlist and either:
                Shift+double-click on those references,
                click on the properties button of the playlist's toolbar,
                choose Properties from Files sub-menu of the playlist's menu.

        The window can also be opened by clicking on the edit track button of
        the music file player control panel while a file is playing.

        The simultaneous edition of the properties of several tracks
        restricts the range of editable properties. The properties which
        differ from one track to another will be displayed in a different
        colour.

        This window allows you to:
           alter the filename of the track (manually or by dragging a file
            from the filer to the edit field).
           open the directory containing the track by clicking on the
            directory icon located on the left of the filename field.
           metadata:
                define the order number of the track into the album.
                alter the title of the track.
                alter the name of the album to which the track belongs.
                specify if the album is independent from the artist
                 (compilation, concert, etc).
                alter the release date of the album, in format YYYY, YYYY-MM
                 or YYYY-MM-DD.
                alter the name of the set to which the album belongs.
                alter the name of artist to which the track belongs.
                alter the name of collective to which the artist belongs.
           replay:
                in the frame of tracks with several sections (or
                 alternatives) to select the section to play.

                 This case often presents itself in the case of files created
                 for games (such as Lemmings) and you are then normally
                 required to change from mode to loop on the track, then to
                 move between sections with the help of the control panel in
                 order to listen to them. A more elegant way to proceed is to
                 insert references to the track in the list as many times as
                 there are sections in the track and to assign a different
                 section to each reference.

                enter notes and comments into an info field.
                give a score/rating to the track.
                set a visual clue to easily find the track in the playlist
                 window.
                define a relative volume expressed as a percentage of the
                 main volume of the control panel allowing you to adjust the
                 volume of this track with regard to the other ones. This
                 volume may be higher than 100% in order to amplify a quiet
                 track.

                 It should be noted that some of the decoders may not allow
                 volumes higher than 100% and thus in this case amplification
                 of the volume will only have an effect when the main volume
                 is lower than 100%. In this frame, if by necessity or habit,
                 you leave the main volume to 100%, I recommend that you use
                 the quietest track in the playlist as a reference and drop
                 the relative volume of the other tracks.

                for the tracks you just keep for the sake of having the
                 complete collection, you can ensure that you will never be
                 able to (manually or through the search window) add them to
                 the list of tracks of the music file player by setting the
                 Play: Never option.
                chain all sections in the track instead of playing a single
                 section by setting the Play: All sections option.
                 It should be noted that when this option is not active, the
                 control panel still allows you to move between the different
                 sections of the file.
           options for the TimPlayer module:
                Ignore sequence loop on last position allows to ignore loops
                 on the last position in the sequence. This avoids the bad
                 usage that some authors make of that feature: loops on empty
                 patterns, loop on textual information (for programs which
                 display the name of the current sample played on each
                 channel), etc.
                Ignore sequence loop restart position lets you loop back
                 from the end of the file to the start of the song sequence
                 instead of to the position specified in the file.
                Ignore end of sequence markers allows to play the sequence
                 sections that follows such markers in some files. Usually
                 these sections only contain trial patterns not included in
                 the final song but sometimes it's quite good (e.g. the S3M
                 'Catch that Goblin!!!').
                 Note: this option is now probably useless due to the newer
                 Play: All sections option.
                Ignore channel muting flags prevents TimPlayer from muting
                 channels which are marked as such in the file.
           ProTracker compatibility options for the TimPlayer module:
                VBlank Mode, Protracker effect Fxx is then always speed,
                 never tempo.
                No Instrument swapping, to keep using the sample data of the
                 old instrument if an instrument without note is specified in
                 Protracker files.
                Ultimate Soundtracker, to treat Soundtracker as old Ultimate
                 Soundtracker (both use the same file format but with
                 different effects). This flag is ignored if the Soundtracker
                 cannot be an Ultimate one (sample sizes > 9999 or usage of
                 effects other than 1xx or 2xx).


                                   Files: Metadata
                                   

        DigitalCD displays in the window file properties some metadata on the
        corresponding track. This data come from several sources, listed here
        in order of priority:
         1  data that you typed in the past in this same window,
         2  data that is extracted from the name of file and of the
            directories which contains it,
         3  data that is extracted from the file's content while listening to
            the track,
         4  and finally, as last resort, the name of the file is used as
            title of the track.

        Data from origin 2 can only come from files referenced by secondary
        lists or directory lists for which a metadata extraction mode was
        defined. The list of available extraction modes comes in two parts:
        DigitalCD's standard modes and user defined modes. We will only cover
        here how the standard modes work (examples).

        The title of each mode comes in the form "path structure | filename
        structure" and provides a synthetic view of how it expects the file
        and directories to be named. So "Artist . Album | Title" essentially
        tells us that using the base directory as a starting point, files are
        expected to be grouped in directories using the artist's name, then
        grouped in sub-directories using the album's name and finally named
        after the track's title. In the same vein, "| Artist - Album - Title"
        tells use that the file is expected to be named by using the names of
        the artist, album and the title separated by hyphens, and that name
        of the directories in which the files are stored are irrelevant.

        This title of course doesn't reflect all the subtleties of the
        extractor's work. A pre-processing is for example performed to
        translate every _ as blanks and every "hard" version of the spaces
        and hyphens in their normal versions. Also, after the text is
        decomposed, a second translation is performed on each extracted
        metadata to transform every / into . (useful for files stored on PCs)
        and every . as blanks.

        Now, at the path level:

           "Artist" refers to the following layout:
                a "various" directory used to regroup files from unknown
                 artists. Eventually files can also be stored in the base
                 directory if no sub-grouping is expected.
                "<artist's name>" directories used to group in the same
                 directory files from the same artist.
                "/ <collective's name>" directories (note the / as prefix
                 for the name) used to group files belonging to the same
                 collective of artists.
                 "various" et "<artist's name>" sub-directories group these
                 files in turn by artist.

           "Album" refers to the following layout:
                a "various" directory used to regroup files from unknown
                 albums. Eventually files can also be stored in the base
                 directory if no sub-grouping is expected.
                "<album's name>" directories used to group in the same
                 directory files from the same album.
                "/ <album set name>" directories (note the / as prefix for
                 the name) used to group files belonging to the same set of
                 albums.
                 "various" et "<album's name>" sub-directories group these
                 files in turn by album.

           The sub-directory "collective" of the base directory is reserved
            to regroup collective albums (and the structure "Artist . Album"
            is inverted in it as "Album . Artist").
           "Collective Album" when used, signal that all the files will
            considered as part of collective albums.

           The last metadata in the title will collect all the directories
            names from the remaining part of the path.
            For example "album . CD1" will become an album named "album CD1".
           Any directory with a name starting with ~ will be ignored.
            So "Artist . ~ Lives . Album" will give an artist "Artist" and an
            album "Album".
           Any directory with a name starting with - will be merged with the
            parent directory.
            So "Name . - Junior . Album" will give an artist "Name Junior"
            and an album "Album".

        At filename level:

           "Artist -" will be interpreted as:
                "" if no hyphen is present in the filename.
                "<artist's name> -" if one hyphen is present.

           "Album -" will be interpreted as:
                "" if no hyphen is present.
                "<album's name> -" if one hyphen is present.
                "<album set name> - <album's name> -" if two hyphens are
                 present.

           "Artist - Album -" will be interpreted as:
                "" if no hyphen is present.
                "<artist's name> -" if one hyphen is present.
                "<artist's name> - <album's name> -" if two hyphens are
                 present.
                "<artist's name> - <album set name> - <album's name> -" if
                 three hyphens are present.

           "( Artist )" will be interpreted as:
                "" when no parentheses are present.
                " ( <artist's name> )" when both parentheses are present.

           If the filename starts with "<nr> -", "<nr> /" (translation of
            the PC notation "<nr> ."), "<nr> )" or even "<nr> <blanks>", <nr>
            being a number, then this number will be used as track number.
           Also, "<variables> - <nr> - <title>" will see the number <nr>
            used as track number.

           "Album" will be interpreted as:
                "[ <album's date> ] <album's name>", if the date is present
                 between [] and in a supported format.
                "<album's name>" otherwise.    

           "Title" will be interpreted as:
                "<title>" if no / is present.
                "<title> / <extension>" where / is the last / present
                 (translation of PC extensions like ".mp3").
         
        Note: the names of variables and special characters in the texts
        above are separated by blanks for clarity. The extraction process
        works perfectly well in their absence and they are just ignored when
        present.


                               Files: Metadata extractors
                               

          DigitalCD provides a list of metadata extractors which analyse the
          name and path of files in order to extract relevant information. If
          those extractors are not suitable for your needs, you can always
          define new ones.

          The directory DigitalCDRes:MetaScan is reserved to store your own
          extractor definitions while DigitalCD's standard extractors, which
          you will certainly use as basis in your first attempts, are stored
          in the directory DigitalCD:StdRes.MetaScan. Each file corresponds
          to a definition and is composed of the following lines:

             Title: <text>

              This line provides a title which will be displayed in the menu
              providing the list of extractors. The title's purpose is to
              provide a synthetic description of the naming structure
              expected by the extractor in the form "path structure |
              filename structure".

             Pre: "<chars>" "<chars>"

              This line defines the character substitutions to apply prior to
              any analysis, such as _ into blank or "hard" version of blanks
              and hyphens into their normal version. The first chain of
              characters provides the list of characters to be replaced and
              the second one, of the same length, the corresponding
              substitution characters.

             Post: "<chars>" "<chars>"

              This line defines as post processing the character
              substitutions to apply on each extracted metadata.

             Join: <char>

              This line defines a directory join character. When this
              character is present as first character in the name of a
              directory, then the name of the that directory will be merged
              with the name of the parent directory for the analysis, meaning
              that the path ".a.-b.c." will be treated as ".a b.c." if - is
              the join character.

             Skip: <char>

              This line defines a directory skip character. When this
              character is present as first character in the name of a
              directory, then the name of that directory will be ignored by
              the analysis, meaning that the path ".a.~b.c." will be treated
              as ".a.c." if ~ is the skip character.

             Date: <char>

              This line defines the meaning of u in a date format like
              <a>-<b>-<year>.
              If the char specified is D or d then a is the day and b is the
              month.
              If the char specified is M or m then a is the month and b is
              the day.

             Path:

              This line tells that every line that follows contains a
              possible alternative in the layout of the path's name.

             Leaf:

              This line tells that every line that follows contains a
              possible alternative in the layout of the file's name.


          Let us detail these layout definition lines:

             [ ... ]   tells that this section is optional
             ( ... | ... | ... ) allows to list alternatives
             \    is an escape character telling that the character that
                   follows must not be interpreted but treated as a normal
                   character. So \[ will be treated as the character [
                   instead of signalling the start of an optional section.
             %x   tells that we are expecting variable x here. BEWARE; you
                   must always leave a blank between x and the rest of the
                   definition. The content of the variable will always be at
                   least one character long and will interrupt itself as soon
                   as what follows allows it, meaning that "%a - %b" will see
                   "x-y-z" decomposed as a="x", b="y-z".
             #x   as %x except that the text may not contain ".". Here are
                   some examples on how to decompose "x.y.z":
                   "%a . %b" gives a="x", b="y.z".
                   "%a . #b" gives a="x.y", b="z".
                   "#a . #b" rejects "x.y.z".
                   "#a . #b [ . %any]" gives a="x", b="y" and ignores ".z".
             blanks    except in the above case blanks are ignored. If you
                        mean to use blanks in the definition, use the
                        variable %space.
             others    the other characters are used as normal characters to
                        define sections of constant text.

          Variables corresponding to metadata:
              name type description
             %title    text title of the track
             %album    text album's name
             %box text name of the set of albums to which the album belongs
             %artist   text artist's name
             %collective    text name of the collective to which the artist
                                  belongs
             %track    number    order number of the track in the album
             %date     date album's date in one of the forms
                             <year>[<sep><month>[<sep><day>]] or
                        [[<day><sep>]<month><sep>]<year>
                        where year is 4 digits, month is 1/2 digits, day is
                        1/2 digits and sep is "-", "/" or ".".

          Other variables:
              name type description
             %any text marks an area of text without meaning
             %comp     void tells the extractor that we are dealing with a
                             collective album.
             %ext text without / used to separate a file extension from the
                                  title
             %space    blanks    tells the extractor that we expect the
                                  presence of one or more blanks here.


                          Files: Metadata extractors in action
                          

          Extractor Artist . Album | Title

             /Five Musicians.Necros.Mechanism Eight/s3m
              Artist    : Necros  Title     : Mechanism Eight
              Collective     : Five Musicians

             Black_Sabbath./Black_Box.Disc _2_-_Paranoid.04_-_Iron Man/mp3
              Artist    : Black Sabbath     Title     : Iron Man
              Album     : Disc 2 - Paranoid Order     : 4
              Album set : Black Box

             Buck-Tick.[1987/04/21] Hurry Up Mode.~Disc 2.0203 Romanesque/mp3
              Artist    : Buck-Tick    Title     : Romanesque
              Album     : Hurry Up Mode     Order     : 203
              Date : 1987-04-21

          Extractor Collective Album . Artist | Title

             /Aria.AriatheNaturalDue.Makino Yui.02/Euforia/flac 
              Artist    : Makino Yui   Title     : Euforia
              Album     : AriatheNaturalDue Order     : 2
              Album set : Aria    Compilation    : true

          Extractor | Album - Artist - Title

             Sound.Albums.Moby - [1999] Play - 01 - Honey/mp3
              Artist    : Moby    Title     : Honey
              Album     : Play    Order     : 1
              Date : 1999


                               Internet radio player
                               

      DigitalCD uses the internet radio player control panel to play internet
      radios stations.

      If you are new to DigitalCD, please start by referring to playing an
      Internet radio.

         Track list and playing order
         Internet radio station properties
         Prerequisites

         Troubleshooting


                 Internet radio player: Track list and playing order
                 

        The list of tracks of the internet radio player is taken from the
        main playlist. Only references preceded by a ticked checkbox are
        considered:

           Internet radio stations are simply added to the track list.
           Unloaded playlists or directory lists are discarded.
           The content of loaded playlists are examined and only internet
            radio stations preceded by a ticked checkbox are added to the
            track list.

        The order in which tracks are played is controlled by the shuffle
        mode. Tracks can be arranged in various ways:

           Tracks can be grouped at several levels: MIME type, bitrate and
            broadcaster.
           Broadcaster groups can be shuffled or sorted alphabetically.

        Within the defined groups, tracks may be:
           Shuffled.
           Sorted alphabetically.


                              Internet radio: Properties
                              

             To open the Internet radio properties window select one or more
             references to radios in a playlist and either:
                Shift+double-click on those references,
                click on the properties button in the playlist's toolbar,
                choose Properties from Internet Radios sub-menu of the
                 playlist's menu.

        The window can also be opened by clicking on the edit track button of
        the Internet radios control panel while a radio is playing.

        The simultaneous edition of the properties of several radios
        restricts the range of editable properties. The properties which
        differ from one radio to another will be displayed in a different
        colour.

        This window allows you to:
           alter the URL used to connect to the radio.
           alter the name of the radio.
           alter the name of the station to which the radio belongs.
           alter the type of the radio.
           enter notes into an info field.
           define the usual bit rate of the radio in kilo bits per second.
           set a visual clue to easily find the track in the playlist window.
           give a score/rating to the radio.
           define a relative volume expressed as a percentage of the main
            volume of the control panel allowing you to adjust the volume of
            this radio with regard to the other ones. This volume may be
            higher than 100% in order to amplify a quiet radio.


                            Internet radio: Prerequisites
                            

        Before you can listen to internet radio you will need to make two
        minor configuration changes to your machine and DigitalCD. You must:

           Update your MimeMap file. The MimeMap file defines the correct
            relationships between the MIME content descriptors and the RISC
            OS filetypes with which they should be associated. (MIME content
            descriptors are used by most internet services, not just internet
            radio stations.)

           Configure DigitalCD with information about your network setup,
            most notably whether or not to use a proxy server. To set up this
            information, please refer to the Internet section of the
            DigitalCD Choices menu.


                                   Sound monitor
                                   

      The sound monitor allows you to treat the output of any sound sampler
      known to DigitalCD as if it was a music track. Playing tracks from the
      sound monitor allows you to use DigitalCD's visualisation plug-ins on
      sounds produced by sources other than DigitalCD itself, including other
      music applications and even external sources such as a microphone.

         Technical information
         Assigning sound samplers to sources 
         SoundDriver configuration


                                  Control panel
                                  

    A control panel is a skinned window controlling how a player's tracks are
    played, and displaying information on the track currently being played.
    Each control panel can take the form of a full-size panel or a mini-bar.

    Full-size Panel


    Mini-bar


    The standard control panel icons are explained below. Note that the
    layout of all of these icons may vary depending on the skin in use, and
    some skins may not provide buttons for every function. All functions are
    however available by clicking MENU over the control panel.

    The standard control panel functions, from left to right and top to
    bottom are:

     1 Window icons    4 Timer           7 Mode switches       10 Move buttons
     2 Title bar       5 Position bar    8 Player custom area                 
     3 Track counter   6 Volume slider   9 Main buttons                       

    There are also a large number of standard keyboard shortcuts.

    To open a control panel open the DigitalCD icon bar menu and choose a
    player from the Players submenu. Clicking on DigitalCD's icon bar icon
    may also open a player control panel. By default, a SELECT-click will
    open the music file player, and an ADJUST-click will open the player
    window for CD drive 0. This behaviour can be altered in the Icon bar
    section of the Choices window, and the behaviour of the different player
    control panels can be adjusted in the Players section of the Choices
    window.


                                Control panel: Skins
                                

      Skins provide an alternative look and feel for the player control
      panels. The skin to be used can be configured from the Skins section of
      the Choices window.

      When a new skin is radically different from the Default skin that comes
      with DigitalCD, use an interactive help program such as Help,
      BubbleHelp or Float to find out the function of the different parts of
      the skin.

      Installing additional skins

      Skins must be installed within DigitalCD's resources directory. New
      skins are supplied as directories which must be copied into the
      !DCDRes.Skins directory. Note that you can create a directory structure
      of your own within the Skins directory if you wish. For example, you
      might want to organise your own skin collection by artist.

                              Creating your own skins


                                   Skins: Creation
                                   

        Skins provide alternative look and feel for the control panels and
        mini-bars of DigitalCD. The skins definitions are stored as
        directories within !DCDRes.Skins and any subdirectory of it. Skins
        can also come as subdirectories of other skins when they are
        providing variants of a given skin.

        A skin definition is a directory containing the following files:

        Mandatory:         Optional:
          Templates          !Help or !ReadMe
          Sprites            Other skins variants (as subdirectories)
          Settings


                                 Skins: Templates file
                                 

          Define the windows Control, ControlCD, MiniCtrl and MiniCtrlCD with
          the list of icons below. If you do not want to use some of the
          icons don't delete them, put them outside the visible area of the
          window.

          The common icons:

          0   Background
          1   Button 'Play'
          2   Button 'Pause'
          3   Button 'Stop'
          4   Button 'Rewind'
          5   Button 'Forward'
          6   Button 'Previous'
          7   Button 'Next'
          8   String 'Track' (anti-aliased font)
          9-10-11-12    Track digits (sprites "0" to "9")
          13-14-15-16-17-18  Time digits (sprites "0" to "9")
          19  Time mode string (anti-aliased font)
          20  Time mode selector (invisible icon covering icons 13 to 19)
          21-22    position bar icons
          23  Volume (sprites "volume0" to "volumex", where x is 20 or as
              specified in Settings file)
          24  Loop Mode (sprites "loop0" to "loop3")
          25  Shuffle Mode (sprites "shuffle0" to "shuffle1")
          26  Intro scan (sprites "intro0" to "intro1")
          27  List Mode (sprites "list0" to "list1")
          28  Track selector (invisible icon covering icons 9 to 12)
          29  Type-Author (anti-aliased font)
          30  Name-Duration (anti-aliased font)
          31  Back icon
          32  Close icon
          33  Pin icon
          34  Mini/Full icon
          39  Volume slider button (optional)

          For CD only:

          35  CD list editor
          37  Open drawer

          For non-CD only:

          35  Remove from play list
          36  Remove from disc
          37  Track properties
          38  Edit playlist

          Note for pointer changes on icons:

          To alter the pointer shape of an icon, add to its validation string:

          Pptr_music    Musical arrow for active areas (bars and buttons)
          Pptr_scrh,11,4     Arrow for horizontal slider buttons
          Pptr_scrv,4,11     Arrow for vertical slider buttons

          Note for templates text colours:

          As I use icons for anti-aliased fonts you have to specify colours
          from the icon validation string with Fxy where x and y are hex
          digits for the background and foreground colour. Note that the
          nested window manager introduce support of full RGB colour
          specification with the validation string Cbbggrr/bbggrr (foreground
          and background rgb hex values) or Cbbggrr (foreground only) or
          C/bbggrr (background only), so you may use them but don't forget to
          include a default Fxy value for those using an earlier version of
          the window manager.


                                  Skins: Sprites file
                                  

          Pretty obviously, the sprites used by the templates.

                                 !!! Very Important !!!

          For 256 colour sprites always use a palette, because there is a bug
           in RISC OS < 4.0 that causes random crashes during redraw of filer
          windows when applications uses 256 colour sprites without a palette.


                                  Skins: Settings file
                                  

          This text file contains the Font settings for the different text
          areas (the font settings defined within the templates are totally
          ignored), and the orientation of volume and position sliders.

          Sections Author, Title, Track, TimeMode

          These sections correspond to the various text fields present in any
          skin: the author (icon 29), the title (icon 30), the "track" text
          (icon 8) and the text of the timing mode used (icon 19). Each of
          these sections contains 3 properties defining the font to use:

                  FontName, the name of the font to use.
                  FontSizeX and FontSizeY, the X and Y size of the font in
                   1/16th of a point.

          Volume section

          The volume slider (icon 23) is defined by the following properties:

                  Vertical, the slide will be horizontal if the value is
                   equal to zero and vertical in any other case.
                  MaxSprite = x tells DigitalCD that when sliding from
                   volume 0 to full volume, the sprite displayed in icon 23
                   will use every sprite from 'volume0' to 'volumex'.
                  Button = 39 tells DigitalCD that icon 39 is used as the
                   volume slider button that will slide within the limits of
                   icon 23. If this property is not defined, no slider button
                   is defined and the user clicks directly on the desired
                   position in the slider.

          PosBar section

          This section is used to use a position bar slider with a slider
          button instead of the traditional slider bar by the addition of the
          line 'Button = 22'.

          In both cases the icon 21, which may be transparent or present use
          a given colour, defines the sliding limits.

          In the traditional slider, the icon 22 is a bar for which you
          define the background colour in the template and of which DigitalCD
          controls the position and size.

          In the case of a slider with button, you must define the icon 22 as
          an icon with indirect text & sprite content, leaving the text empty
          and with a validation string like 'Sbarb,pbarb;Pptr_scrh,11,4'.


                            Control panel: Window icons
                            

         The back icon moves the window to the back of the window stack.
         The close icon closes the window.
         The pin icon iconises the window.
         The minimise icon turns a full-size control panel into a mini-bar.
         The maximise icon turns a mini-bar back into a full-size control
         panel.


                              Control panel: Title bar
                              

      The title bar contains two lines of text.

      One line displays the track title and its total duration. Note that
      this information may not be correct for some tracker formats, which may
      contain more than one tune, and/or looped tunes that repeat forever.

      The second line cycles through other available information such as
      album name, artist or track format. 'Track format information' includes
      the filetype, the number of channels, and some other technical
      information relevant to the file being played.



                            Control panel: Track counter
                            

      The track counter shows the number of the track currently being played.
      Clicking on the counter will open a list from which a new track can be
      chosen.


                                Control panel: Timer
                                

      The timer has six available modes on which you can cycle by clicking
      SELECT or ADJUST on the timer. These modes are: elapsed time, remaining
      time, duration, total elapsed time, total remaining time and total
      duration. Their definitions change somewhat with the kind of track
      played.

         When playing a file, the usual timings refer to the current section
          within the track while the totals refer to the whole track (and
          usually display the same values as most of the files contain only
          one section).

          Note: when you are playing some tracker files temporal information
          is not available and a pseudo time is displayed based on the
          current pattern and line within the pattern. Given the replay speed
          of patterns you will experience time dilatation or time compression
          effects and you will even travel back in time due to program loops
          in the patterns. ;-)

         When playing an Internet radio, the total elapsed time and total
          duration refer to the time elapsed since you started listening to
          this radio, the elapsed time refer to the current title played by
          the radio (if detectable). The total remaining time refers to the
          content of the replay buffer and finally the duration being unknown
          refer to the highest elapsed time achieved till now.

         When playing a CD, normal timings refer to timings within the
          current track, while totals refer to timings for the whole CD.


                            Control panel: Position bar
                            

      The position bar is a graphical representation of the current position
      within the played track. Depending on the skin in use the position bar
      may or not have a slider button. To modify the position move the slider
      to the desired position if one is present, otherwise click directly on
      desired position on the bar.


                            Control panel: Volume slider
                            

      The volume slider is a graphical representation of the main volume of
      the player. Depending on the skin in use the volume bar may be vertical
      or horizontal and may or not have a slider button. To modify the volume
      move the slider to the desired position if one is present, otherwise
      click directly on desired position on the bar.

      Important Note:

      While playing a music file or an Internet radio you can edit its
      properties and specify a scale volume (as a percentage of the main
      volume). I recommend that you set the main volume to an adequate value,
      then for each track in the playlist alter the relative volume. This
      will ensure that once the playlist is saved you will no longer need to
      fiddle with the main volume slider on each track change.


                            Control panel: Mode switches
                            

      The mode switches alter the way in which tracks are played. By clicking
      with SELECT or ADJUST, you can cycle the possible values of each of the
      following switches:

         Program

             When active, allows you to play an alternative list of tracks to
             the list of tracks played normally by the player:

                For a CD player, DigitalCD will play the tracks which belong
                 to the preference list of the current CD instead of the
                 default list of all the tracks which belong to the current
                 CD.

                For the music file player, DigitalCD will play the tracks
                 listed in the file queue instead of the files listed in the
                 main playlist. Settings in the Choices window, Files section
                 may allow you when dropping a file on the panel or on the
                 icon bar icon to automatically add the file to the file
                 queue, turn the program on and start playing the file
                 without disturbing the main playlist.

         Shuffle

             When set DigitalCD shuffles the tracks before starting to play
             so that they are played in a different order. This differs of a
             truly random mode as here a track will never be played a second
             time before all the other tracks have been played at least once.
             The Choices window, Players section, allows opting for an
             automatic reshuffle of the list once all tracks in the list have
             been played in order to avoid playing the list in the same order
             as in the previous loop.

             It should be noted that the music file player and internet radio
             player offer far more advanced shuffling options. A click with
             SELECT on the shuffle icon shows those options in a menu while a
             click with ADJUST toggle shuffling on/off. The options listed
             allow the arrangement of tracks in various ways:

                Files can be grouped at several levels: collective, artist,
                 album set, album.
                Files from compilation albums follow the same level grouping
                 order as normal albums unless compilation is selected. In
                 that case the level grouping order becomes album set, album,
                 followed by collective, artist if by artist is selected.
                Radio stations can be grouped at several levels: MIME type,
                 bitrate, broadcaster.
                Groups can be shuffled or sorted alphabetically at each
                 level of grouping.

             Within the defined groups, tracks may be:
                Shuffled.
                Sorted alphabetically.
                Following the album order (album grouping must be active).

         Repeat

             Normal play, plays the tracks in the list and stops.
             Loop on list, loops on the tracks in the list.
             Loop on track, loops on the played track.
             Play single track, plays the track till its end before stopping.
             It allows to cleanly end your listening session and to restart
             the next session from the next file (assuming an identical list
             without shuffling).

         Intro scan

             When set, DigitalCD will only play the start of the tracks,
             allowing you to search for a track which you now only the melody
             of. The Choices window, Players section defines the duration of
                 the intro scan.


                             Control panel: Custom area
                             

      The content of this section depends on the type of player.

      For a CD player there may be icons shown to:

         open the CD Database window,
         open the CD drawer.

      For the music file player there are four icons 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 (SELECT),
                 show the playlist containing the current track (ADJUST),
                open the main playlist (SELECT),
                 open the file queue (ADJUST).

      For the internet radio player there are four icons shown to:

                remove the current track from the playlist,
                edit the properties of the current track (SELECT),
                 show the playlist containing the current track (ADJUST),
                open the main playlist.


                            Control panel: 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 stops the playback.


                            Control panel: Move buttons
                            

             Rewind allows you to move back within the current track (when
             the Shift key is pressed at the same time you move back to the
             previous section within the track).

             Fast forward allows you to move forward within the current track
             (when the Shift key is pressed at the same time you move to the
             next section within the track).

             Previous allows you to move to the previous track.

             Next allows you to jump to the next track.


                         Control panel: Keyboard shortcuts
                         

      Key Action
      
      Space/Return  Play/Pause
      + Shift  Move back to the start of the current section of the played
               track
      + Ctrl   Move back to the start of the played track
      Esc Stop

      Left Arrow    Rewind, move back in the played track
      Right Arrow   Forward, move forward in the played track
      Shift + Left  Move back to the start of the previous section in the
                    played track
      Shift + Right Move to the start of the next section in the played track
      Ctrl + Left   Previous track
      Ctrl + Right  Next track

      Ctrl + Page Up     Increase the main volume of the player
      Ctrl + Page Down   Decrease the main volume of the player
      Ctrl + Up     Finely increase the main volume of the player
      Ctrl + Down   Finely decrease the main volume of the player

      I   Switch intro scan on/off
      P   Switch program on/off
      R, Shift + R  Cycle on repeat modes
      S   Switch shuffle on/off
      T, Shift + T  Cycle on timer modes

      Ctrl + K Start configured plug-ins
      Ctrl + Shift + K   Stop all plug-ins

      CDs:

      Ctrl + Insert Open CD database

      Music files:

      Page Up  Increase the relative volume of the played track
      Page Down     Decrease the relative volume of the played track
      Up Arrow Finely increase the relative volume of the played track
      Down Arrow    Finely decrease the relative volume of the played track

      Insert   Edit the properties of the played track
      Shift + Insert     Open the playlist containing the played track
      Ctrl + Insert Open the main playlist
      Ctrl + Shift + Insert   Open the file queue

      Delete   Remove the played track from its playlist
      Ctrl + Delete Delete the file corresponding to the played track

      Internet radios:

      Page Up  Increase the relative volume of the played track
      Page Down     Decrease the relative volume of the played track
      Up Arrow Finely increase the relative volume of the played track
      Down Arrow    Finely decrease the relative volume of the played track

      Insert   Edit the properties of the played track
      Shift + Insert     Open the playlist containing the played track
      Ctrl + Insert Open the main playlist

      Delete   Remove the played track from its playlist


                                   CD database
                                   

    The CD database can be opened directly from the DigitalCD icon bar menu
    or by clicking the Edit icon in the CD player control panel. In
    DigitalCD's default skin, the Edit icon is the Compact Disc logo shown
    below:




    The CD database window may be displayed as a list or as a tree view.

     Tree view groups     CD(s) properties         Marking references    
     Display options      CD track(s) properties   Searching references  
     Keyboard shortcuts                            Miscellaneous commands

    Notes

    DigitalCD stores the code returned by the command *WhichDisc (usually six
    digits) as an identifier for each CD it plays. This code is displayed as
    default title for the CD.

    DigitalCD can be configured to use AcornCD to retrieve CD descriptions
    from the internet, which means you don't have to type in the descriptions
    yourself.


                         CD database: Grouping information
                         

      Information of the CD Database in tree view mode may be presented in
      groups of the following types:

          Collective of artists.
          Artist.
          Set of compilation albums.
          Set of albums.
          Compilation album.
          Album.
          CD tracks.


                                CD database: Search
                                

           The search window can be opened by clicking on the CD database's
           search tool, by choosing Search from the Marks submenu or by
           pressing F7.

      This window allows you to act on playlist references within a given
      scope and matching one of the defined search criteria. The default
      action is to List all matching references in a search results window.

      The possible search criteria are:

         All  to act on all references.
         Metadata  to act on all references whose metadata (title, album,
                    artist, etc) contains the given search string.


                             CD database: Search actions
                             

        The possible actions to perform on matching references are:

               List to list the reference in a search results window.

               Mark to set a mark before the reference.
               Unmark    to remove the mark before the reference.

               Selected  to add the reference to the selection.
               Unselected     to remove the reference from the selection.


                              CD database: Search scope
                              

        The possible scopes are:

               Whole database to find a match within all references within
                               the whole CD database.

               Marked    to find a match only within already marked
                          references.
               Unmarked  to find a match only within not yet marked
                          references.

               Selected  to find a match only within already selected
                          references.
               Unselected     to find a match only within not yet selected
                               references.


                          CD database: Search results window
                          

        A search results window is a temporary playlist containing links to
        the references matching a performed search operation.

        Several operations can be performed on the results of a search,
        including:
           removing references from the results window,
           editing the properties of one or more references, any change made
            will affect the original versions.


                        CD database: Miscellaneous commands
                        

      Save

               This command allows you to save the changes made to the
               database.

      Properties

               This command is available only when all select references are
               of the same type. It allows you to alter the properties of one
               or more reference at the same time. Refer to the description
               of the different type of references for more details.

               See CD(s) properties, CD track(s) properties.

      CD Properties

               This command allows you to alter the properties of the CDs
               related to your selection.

      Reload

          This command allows revert all changes made to the database since
          the last save.

      Delete CD

          This command allows you to remove a CD description from the
          database.


                                     Playlist
                                     

    A playlist is a list of objects that can be used to define the list of
    tracks to be played by the music file player or the internet radio
    player. A playlist may be displayed as a list or as a tree view. The CD
    players and the sound monitor don't make any use of these playlists.

    Objects come in several kinds.

       Playable objects:
        Files,
        Internet radio stations.

       Playlists. The main playlist may contain one or more:
        Secondary lists,
        Directory lists,
        Imported lists,
        Yellow pages.

       Links. They refer to objects stored in other playlists. Any
        modification on these links like editing their properties will
        actually directly alter the original objects. Links cannot be stored
        so only temporary playlists like the file queue and search results
        can use them.

   Layout of playable references   Adding files to the list   Marking
                                                              references    
   Layout of list references       Cut and paste, deleting    Searching
                                                              references  
   Tree view groups                Drag and drop              Miscellaneous
                                                              commands
   Display options                 Keyboard shortcuts


                                   Main playlist
                                   

      The main playlist is a permanent playlist which contains references to
      objects that can possibly be played by the music file player or the
      internet radio player. It also contains the references to other
      playlists:
             Secondary playlists.
             Directory lists.
             Yellow pages.

      The music file player and the internet radio player use the content of
      the main playlist to determine the list of tracks they will play.

      The main playlist window can be opened by choosing Main playlist from
      the DigitalCD icon bar menu or from the music file player. Depending on
      the configuration in the Icon bar section of the Choices window,
      clicking SELECT or ADJUST on the DigitalCD icon bar icon may also open
      the main playlist.

      Other playlists window can be opened by double-clicking on their
      references in the main playlist. Note that closing a playlist window
      does not remove the document from memory but merely hides it from sight.

       Managing secondary playlists   Secondary playlist properties
       Managing directory lists       Directory list properties    
       Managing yellow pages          Yellow page properties       
       Miscellaneous commands                                      


                                 Secondary playlist
                                 

          A secondary playlist is a permanent playlist stored at the location
          of your choice as a FileList file (filetype 155) and containing
          references to objects that can be played by the music file player
          or the internet radio player.

      All secondary playlists are managed from the main playlist.

      The playlist's window is opened by double-clicking on its reference in
      the main playlist. Note that closing a playlist window does not remove
      the document from memory but merely hides it from sight.

       Managing secondary playlists   Secondary playlist properties


                             Secondary playlist: Managing
                             

        Creating a playlist

             From the main playlist click on the create playlist button. A
             new dialog box will appear allowing you to define its
             properties. Press Set, the new playlist will be listed in the
             main playlist and opened on screen.

        Saving a playlist

        The main playlist is automatically saved in a standard location on
        exit of DigitalCD but you have to explicitly save the other lists to
        a location of your choice. 

             From the playlist window click either SELECT or ADJUST on the
             Save button or press F3 or Shift+F3. In the first case a
             standard Save as dialog box will be proposed while in the second
             case the file will be saved under its current filename.

        DigitalCD splits modifications to a playlist into two categories:
        status/properties updates (played, volume scale update, etc) and
        contents update (copy, delete, etc). If on exit from DigitalCD, or
        when unloading the playlist, only changes of the first category
        occurred, DigitalCD will save the updated playlists automatically
        while it will explicitly ask you to save changes falling into the
        second category to prevent the saving of accidental modifications.

        Adding a playlist

        A reference to a playlist file can be added to the main playlist by a
        double-click on the file's icon or by dragging it to the DigitalCD
        icon bar icon. Never drag the file to the main playlist as this
        operation will insert the list's content into the main playlist (like
        when you drag a text file into an existing document).

        Removing a playlist

             To remove a playlist, simply select it from the main playlist
             and use either of the Cut or Delete commands.

        Loading and unloading the list's content

        By default the content of playlists is automatically loaded when
        DigitalCD starts but each list can be individually configured not to
        load at startup.

        To load or unload the list's content, select the list from the main
        playlist and choose Load or Unload from the Lists submenu.


                            Secondary playlist: Properties
                            

             To open the Playlist properties window select or more references
             to lists from the main playlist and either:
                Shift+double-click on those references,
                click on the properties button of the main playlist's
                 toolbar,
                choose Properties from the Lists sub-menu of the main
                 playlist's menu.

        Altering several lists at once restricts the range of properties that
        can be edited. The properties which differ from one list to another
        will be displayed in a different colour.

        This window allows you to:
           alter the filename of an unloaded secondary playlist (manually or
            by dropping a file from the filer),
           alter the base directory of a secondary playlist (manually or by
            dropping a directory from the filer),
           let DigitalCD extract metadata from the filenames of file
            references when loading the list,
           alter the title of the list,
           alter the author of the list,
           enter notes into an info field,
           tell DigitalCD to automatically load the contents of the list
            when DigitalCD starts.


                                   Directory list
                                   

          A directory list is a playlist containing a snapshot of the
          contents of the directory it is based upon. The list's file
          references and their properties are never saved; if you want to
          preserve the information generated, copy the items into a normal
          playlist. The purpose to directory lists is to provide a quick way
          to access directories, either:
                  organised, where the names of the subdirectories and the
                   name of the files allows to retrieve the most common
                   metadata of the files like the artist, the album or its
                   title.
                  temporary, such as the commonly-used <MP3$Dir>, used by
                   many people to store MP3 files they have just downloaded.

      Directory lists are managed from the main playlist.

      A directory list's window is opened by double-clicking on its reference
      in the main playlist. Note that closing a playlist window does not
      remove the document from memory but merely hides it from sight.

       Managing directory lists   Directory list properties


                               Directory list: Managing
                               

        Creating a directory list

             From the main playlist click on the create directory list
             button. A new dialog box will appear allowing you to define its
             properties. At the very minimum, you must define a base
             directory of the directory list. Press Set, the new directory
             list will be listed in the main playlist and DigitalCD will
             start loading its content (see below).

        Removing a directory list

             To remove a directory list, simply select it from the main
             playlist and use either the Cut or Delete commands.

        Loading and unloading the content of a directory list

        The loading operation recursively scans the base directory and its
        sub-directories to add all the files found with an acceptable
        filetype.

        By default, directory lists are automatically loaded when DigitalCD
        starts but each list can be individually configured not to load at
        startup.

        To load or unload a directory list's content, select the list from
        the main playlist and choose Load or Unload from the Directory lists
        submenu.

        Refreshing the list's content to reflect changes in the directory is
        a simple matter of unloading the list and then loading it again.


                              Directory list: Properties
                              

             To open the directory list's properties window select one or
             more references to directory lists from the main playlist and
             either:
                Shift+double-click on those references,
                click on the properties button of the main playlist's
                 toolbar,
                choose Properties from the Directory lists sub-menu of the
                 main playlist's menu.

        Altering several directory lists at once restricts the range of
        properties that can be edited. The properties which differ from one
        directory list to another will be displayed in a different colour.

        This window allows you to:
           alter the base directory of a directory list (manually or by
            dropping a directory from the filer),
           let DigitalCD extract metadata from the filenames of file
            references when loading the directory list,
           alter the title of the directory list,
           alter the author of the directory list,
           enter notes into an info field,
           tell DigitalCD to automatically load the contents of the
            directory list when DigitalCD starts.


                                   Imported list
                                   

          An imported list is a permanent playlist stored at the location of
          your choice which is in a format other than DigitalCD's usual
          playlists. Supported lists are M3U (filetype AA7) and PLS (filetype
          AA8). Both types contain a list of internet radio stations
          references.

      All imported lists are maintained from the main playlist.

      The imported list window is opened by double-clicking on its reference
      in the main playlist. Note that closing the window does not remove the
      document from memory but merely hides it from sight.

       Managing imported lists   Imported list properties


                               Imported list: Managing
                               

        Saving a list

             From the list window click either SELECT or ADJUST on the Save
             button or press F3 or Shift+F3. In the first case a standard
             Save as dialog box will be proposed while in the second case the
             file will be saved under its current filename.

        It should be noted that most/all properties of the items in your list
        will be lost because the imported list's format does not support them.

        Adding a list

        A reference to an imported list file can be added to the main
        playlist by a double-click on the file's icon or by dragging it to
        the DigitalCD icon bar icon. Never drag the file to the main playlist
        as this operation will insert the list's content into the main
        playlist (like when you drag a text file into an existing document).

        Removing a list

             To remove a list, simply select it from the main playlist and
             use either of the Cut or Delete commands.

        Loading and unloading the list's content

        By default the content of lists is automatically loaded when
        DigitalCD starts but each list can be individually configured not to
        load at startup.

        To load or unload the list's content, select the list from the main
        playlist and choose Load or Unload from the Lists submenu.


                              Imported list: Properties
                              

             To open the imported list properties window select or more
             references to imported lists from the main playlist and either:
                Shift+double-click on those references,
                click on the properties button of the main playlist's
                 toolbar,
                choose Properties from the Lists sub-menu of the main
                 playlist's menu.

        Altering several lists at once restricts the range of properties that
        can be edited. The properties which differ from one list to another
        will be displayed in a different colour.

        This window allows you to:
           alter the filename of an unloaded list,
           alter the title of the list,
           alter the author of the list,
           enter notes into an info field,
           tell DigitalCD to automatically load the contents of the list
            when DigitalCD starts.


                                    Yellow page
                                    

          Yellow pages are playlists whose content is downloaded from the
          internet. The yellow page contains a list of internet radio
          stations references. The references and their properties are never
          saved. If you want to preserve this information, copy the data into
          a normal playlist. The largest downloadable yellow page I know of
          is http://dir.xiph.org/yp.xml but you can use the URLs of large
          .m3u or .pls files you may happen to know.

      All yellow pages are maintained from the main playlist.

      The yellow page window is opened by double-clicking on its reference in
      the main playlist. Note that closing a playlist window does not remove
      the document from memory but merely hides it from sight.

       Managing yellow pages   Yellow page properties


                                Yellow page: Managing
                                

        Creating a yellow page

             From the main playlist click on the create yellow page button. A
             new dialog box will appear allowing you to define its
             properties. Define at least the URL of the yellow page (like
             http://dir.xiph.org/yp.xml or the URL of an .m3u or .pls file)
             and press Set, the new yellow page will be listed in the main
             playlist and DigitalCD will start to download its content from
             the Internet.

        Removing a yellow page

             To remove a yellow page, simply select it from the main playlist
             and use either the Cut or Delete commands.

        Downloading and unloading the list's content

        In the case of a yellow page the loading operation attempts to
        download its content from the specified URL on the Internet.

        The yellow page can be configured to load automatically at startup.

        To load or unload the list's content, select the list from the main
        window and choose Download or Unload from the Lists submenu.


                               Yellow page: Properties
                               

             To open the Yellow page properties window select or more
             references to yellow pages from the main playlist and either:
                Shift+double-click on those references,
                click on the properties button of the main playlist's
                 toolbar,
                choose Properties from the Yellow Pages sub-menu of the main
                 playlist's menu.

        Altering several yellow pages at once restricts the range of
        properties that can be edited. The properties which differ from one
        yellow page to another will be displayed in a different colour.

        This window allows you to:
           alter the URL of an unloaded yellow page,
           enter notes into an info field,
           tell DigitalCD to automatically load the contents of the yellow
            page when DigitalCD starts.


                      Playlist: Layout of playable references
                      

      Each reference may show the following information:

         Play selection. Informs you whether the reference is to be included
          in the lists of tracks to be played by the music file player or the
          internet radio player.

          Ticked, the reference is included in the track list.
          Not ticked, the reference is excluded from the track list.

          Nothing to tick, the reference has the property Never Play and as
          such is cannot be included in the track list.

         Reference type icon.

          File.
          Internet radio.

         Hint marks.

          The reference's visual clue.
          A search result mark.
          A link mark, denoting a link to the reference stored in another
          list and that editing its properties will directly alter the linked
          reference.

         Play marks.

          Nothing if the referenced object was never played.
          A black triangle if the referenced object is being played.
          A green tick if the referenced object was played during the current
          session.
          A grey tick if the referenced object was played during a previous
          session.
          A red cross if the last attempt to play of the referenced object
          failed.
          A question mark if the Validate command thinks the reference to the
          object is incorrect.

          All these marks within a list can be cleared by choosing Clear Play
          Marks command from the list's Marks submenu.

         The object's title or a substitute in its absence.


                        Playlist: Layout of list references
                        

      Each list reference may show the following information:

         Play selection. Informs you whether the list's content is to be
          included in the list of tracks to be played by the music file
          player or the internet radio player.

          Ticked, all references themselves ticked within the list are
          included in the track list.
          Not ticked, the list's content is excluded from the track list.

         List type and status icons. The icon is greyed when the list is not
          loaded in memory.

          The icon of a directory with notes for a secondary list.
          The icon of a directory for a directory list.
          The icon of a directory with a network mark for yellow pages.

         Hint marks.

          A search result mark.
          A link mark, marking a link to the reference stored in another list
          and that editing its properties will directly alter the linked
          reference.

         Access marks.

         Nothing if the referenced list was never loaded.
         A green tick if the referenced list was loaded successfully during
         the current session.
         A grey tick if the referenced list was loaded successfully during a
         previous session.
         A red cross if the last attempt to load the referenced list failed.
         A question mark if the Validate command thinks the reference to the
         list is incorrect.

         The list's title or a substitute in its absence.


                           Playlist: Grouping information
                           

      Information of a playlist in tree view mode may be presented in groups
      of the following types:

          Internet radios.
           Internet radios type.
           Internet radios broadcaster.
           Internet radios bandwidth.

          Playlists.

          Music files.
           Collective of artists.
           Artist.
           Set of compilation albums.
           Set of albums.
           Compilation album.
           Album.


                             Playlist: Display options
                             

      Clicking MENU on the playlist and following the Display submenu allows
      you to alter the way references are displayed in the list.

         Hierarchical

          When set, the playlist is displayed as a tree view with the
          possibility to fold/unfold groups of references. When unset the
          playlist is displayed as a list.

         Group by

          Lists the possible groupings of references that can be made.
          Internet radios can be grouped by broadcaster and bandwidth.
          Files can be regrouped by collective, artist, album set, album,
          compilation (and by artist within the compilation). In the usual
          grouping by artist and album, if compilation is left unticked,
          compilation albums are split by artists and the relevant parts
          listed as an album of each artist.

         Sort by

          Lists the possible ways to sort tracks within the playlist or
          within each group. The groups themselves are always sorted in
          alphabetical order.
          References can be sorted to follow the album order (usually used in
          combination with album grouping), can be sorted in alphabetical
          order by track name or can be leaved unsorted.

         Use default

          Select this option to reset the display options to their defaults.

         Set as default

          Select this option to use the current display options as default
          for all playlists. Note that normal playlists and search results
          window use a separate defaults.


                               Playlist: Adding files
                               

      The usual way to add files to a playlist is to drag the files from the
      Filer to the position within the list where you wish to insert the
      files. Only references to files with an accepted filetype will be
      inserted in the list.

      More conveniently, you can also drop directories onto the playlist. The
      content of the directory and its subdirectories will be scanned and
      references to all files found with an accepted filetype will be
      inserted in the list.

      Finally depending on your settings in the Choices window, Files
      section, files may be added to the main playlist as the result of
      actions like double-clicking on a file or dragging the file to the
      DigitalCD icon bar icon or to the music file player.


                         Playlist: Cut and paste, deleting
                         

      Cut and paste


      Standard global clipboard operations Cut, Copy and Paste and their
      shortcuts Ctrl+X, Ctrl+C, Ctrl+V are implemented within playlists.
      Select references in the playlist, cut or copy them to the clipboard
      then move the cursor to the desired location in the list (or into
      another one) and paste the clipboard's content into the list.

      There are two restrictions to this scheme:
         only simple references are copied to the clipboard, not references
          to playlists or directory lists.
         when pasting a section of a FileList file (type 155) from a text
          editor, pay attention to paste only references containing a full
          path in their filename or URL.

      To delete references without moving them to the clipboard use Delete
      (Del).

      Deleting referenced files

      Cut and Delete operations will only remove the selected references from
      the playlist. If in addition you wish to physically delete the
      referenced files use the Delete Files command (Shift+Del). As a measure
      of safety you will be asked for confirmation of the operation.


                              Playlist: Drag and drop
                              

      Cut and paste operations can be done with the mouse by drag and drop of
      the selection as long as the selection consists only of references to
      playable objects (i.e. no playlists nor any tree view groups).
      Alternatively you can drag a tree view object's icon or a group's icon
      to drag all the references it contains.

      As soon as you start dragging the selection/icon you will see the
      pointer turn into a dragging pointer combined with a special sign
      reflecting the operation that will follow the drop at the current
      position of the pointer. The operation defaults to a copy unless the
      playlist is displayed as a raw list (no tree view, no grouping and no
      sorting) where the default is a move as it is possible to reorganise
      the order of references in the playlist.

      Drag and drop isn't limited to the original playlist and the default
      operation reverts to a copy as you leave the original window. The final
      destination can be another playlist or even the DigitalCD icon bar icon
      in which case the operation creates a new playlist.

      If you start pressing Shift while dragging an alternate operation is
      usually proposed (a move instead of a copy or vice versa).

      When dragging over a playlist, position the mouse within the list near
      its border and the window will scroll automatically. Also on playlists
      displayed as raw lists a red caret appears within the playlist
      following the pointer to reflect the point of insertion for the dragged
      references.

      The sign in the pointer shape will be updated to reflect changes in
      operations caused by Shift pressing or by changes of destination:
         a minus to indicate that the references will be moved.
         a plus to indicate a copy of the references will be inserted.
         a link to indicate that links to the references will be inserted.
         a forbidden sign when the drop will have no effect.
         a question mark when it is not known how the application below the
          pointer will react.

      Drop the references to complete the action or press Esc to abort the
      operation.


                            Playlist: Keyboard shortcuts
                            

      Key Action
      
      Insert   Toggle the linkage between cursor and selection on/off
      Shift + Insert     Start/Stop a SELECT like selection
      Ctrl + Insert Start/Stop an ADJUST like selection
      Space    Toggle the selection status of the current reference
      Ctrl + A Select all references in the list
      Ctrl + Z Clear the selection

      Ctrl + X Cut the selection to the clipboard
      Ctrl + C Copy the selection to the clipboard
      Ctrl + V Paste the clipboard into the list
      Delete   Remove the selection without a copy to the clipboard
      Shift + Delete     Physically delete the files referenced in the
                         selection

      Return   Open the properties window for the current reference
      Shift + Return     Open the current list reference's window

      F3  Open the Save as box
      Shift + F3    Save the list under its current filename

      F7  Open the Search window

      F11 Mark the selection
      Shift + F11   Remove marks from the selection
      Ctrl + F11    Move the cursor to the previous mark
      Ctrl + Shift + F11 Move the cursor to the next mark


                            Playlist: Marking references
                            

           Marks can be set to easily navigate within the playlist. Just
           select the references to be marked and press F11 or choose Set
           Mark from the Marks submenu. Marks can also be set from the Search
           window when you are looking for references matching certain
           criteria.

      Once you have marked references, pressing Ctrl+F11 (Ctrl+Shift+F11) or
      choosing Previous (Next) Mark from the Marks submenu will move the
      cursor to the previous (next) mark. 

      To remove marks, select the references to be unmarked and press
      Shift+F11 or choose  Remove Mark from the Marks submenu.

      To clear all marks, choose  Clear Marks from the Marks submenu.


                                  Playlist: Search
                                  

           The search window can be opened by clicking on the playlist's
           search tool, by choosing Search from the Marks submenu or by
           pressing F7.

      This window allows you to act on playlist references within a given
      scope and matching one of the defined search criteria. The default
      action is to List all matching references in a search results window.

      The possible search criteria are:

         All  to act on all references.

         Clue to act on all tracks matching the given visual clue or, if no
               clue is given, to act on all tracks lacking a visual clue.

         Filename  to act on all references whose filename contains the
                    given search string.
         Metadata  to act on all references whose metadata (title, album,
                    artist, etc) contains the given search string.

         Unrated   to act on all unrated tracks.
         Points    to act on all tracks matching the given condition.


                               Playlist: Search actions
                               

        The possible actions to perform on matching references are:

               List to list the reference in a search results window.

               Mark to set a mark before the reference.
               Unmark    to remove the mark before the reference.

               Set as to play to set the reference's 'to play' tick.
               Set as not to play  to remove the reference's 'to play' tick.

               Selected  to add the reference to the selection.
               Unselected     to remove the reference from the selection.


                                Playlist: Search scope
                                

        The possible scopes are:

               All playlists  to find a match within all references of all
                               playlists.
               Playlist  to find a match within all references within the
                          current playlist.

               Marked    to find a match only within already marked
                          references.
               Unmarked  to find a match only within not yet marked
                          references.

               To play   to find a match only within references that you
                          ticked as to play.
               Not to play    to find a match only within references that
                               you did not tick as to play.
               Never play     to find a match only within tracks with that
                               property (and which cannot be ticked). 

               Selected  to find a match only within already selected
                          references.
               Unselected     to find a match only within not yet selected
                               references.

               Playing   to locate the playing track.
               Played    to find a match only within already played tracks.
               Not played     to find a match only within not yet played
                               tracks.
               Failed to play to find a match only within tracks that
                               DigitalCD could not play.
               Invalidated    to find a match only within invalidated
                               references.


                           Playlist: Search results window
                           

        A search results window is a temporary playlist containing links to
        the references matching a performed search operation.

        Several operations can be performed on the results of a search,
        including:
           removing references from the results window,
           editing the properties of one or more references, any change made
            will affect the original versions, even if the references
            originate from several playlists.
           dragging references to the file queue to insert new links to the
            original references in that list.
           dragging references to another playlist to insert copies of the
            original references in that list.
           dragging references to the DigitalCD icon bar icon to create a
            new playlist.


                          Playlist: Miscellaneous commands
                          

      Validate

          This command scans the list and marks with a "?" all references
          corresponding to a non-existing file or files with an incorrect
          filetype. This command is useful for locating deleted, renamed or
          moved files. However, pay attention that it will also mark
          references accessed through currently unstarted filing systems
          (SparkFS, IZipFS, etc).

      Complete

          This command scans the base directory associated to a list and all
          its subdirectories to insert missing music files to the playlist.
          It allows you to actualise the playlist after adding files or
          albums to your collection.

           Properties

          This command is available only when select references are of the
          same type. It allows you to alter the properties of one or more
          reference at the same time. Refer to the description of the
          different type of references for more details.

          File properties
          Internet radio station properties
          Secondary playlist properties
          Directory list properties
          Yellow page properties

           Play

          This command is available only if you selected a single reference
          ticked as to be played. It activates the appropriate player and
          forces it to play the selected reference or, in the case of a
          playlist reference, the first playable reference in the playlist.


                                     File queue
                                     

      The file queue is a playlist containing references to files that will
      be played by the music file player when its program mode is active.
      This playlist is not saved on exit of DigitalCD.

      The file queue window may be opened by choosing File queue from the
      DigitalCD icon bar menu or from the music file player. Depending on the
      configuration in the Choices window, Icon bar section, clicking SELECT
      or ADJUST on the DigitalCD icon bar icon may open the playlist too.

      The two usual ways to use the file queue are:
         Playing files not part of your playlists by dragging to its window
          files or directories directly from the Filer. This allows you to
          define a temporary playlist without affecting your existing
          playlists.
         Playing a subset of your playlists, such as a particular album or
          all tracks by a given artist, by dragging to its window files
          references from other playlists. This will not copy these
          references but merely insert links to the original references so
          that changes (extracted metadata, relative volume changes, etc)
          will update the original references.


                              Playlist: Base directory
                              

      The base directory of a playlist is the name of a directory which
      should contain of all file referenced in your playlist. The file
      references whose path contains the base directory are kept relative to
      the base directory. It offers several advantages:

         These references take less space in memory and in the saved
          playlist files.
         If you decide to move that directory to another location on your
          harddisk or to another harddisk, you don't have to fix the path of
          each reference in the playlist, you just update the base directory
          of the playlist and all references are fixed in one go.
         Most of the time files are not placed at random in this base
          directory but are named and regrouped in subdirectories based on
          metadata from the files like the track's number and name, the name
          of the artist of the album, etc. This means that using the base
          directory as a starting point DigitalCD can guess some of the
          file's metadata from the remaining part of the filename.
         You can use the Complete command to scan the base directory and its
          subdirectories and insert in the playlist music files which were
          missing in the playlist.


                                     Choices
                                     

    The Choices window configures various aspects of DigitalCD. To configure
    DigitalCD open its icon bar menu and choose Choices. Unless the default
    icon bar configuration has been altered, clicking Ctrl-SELECT or
    Ctrl-ADJUST on the DigitalCD icon will also open the Choices window.

    The Choices window is divided into two areas. There is an expandable
    configuration tree showing various sections and sub-sections on the
    right, and the contents of the currently-selected section on the left. To
    switch to a different section, click on its name in the configuration
    tree.

    Changes in the window will not take effect until they have been applied
    by clicking either Save or Set. The following exceptions apply:

       Changes made in the Mixing and Equalizer sections are applied in
        real-time for testing purposes. However, the settings will revert to
        their original values if you close the dialog box or click Cancel.
       Some driver options will only take effect when the next track is
        played.

    Clicking Set will make the changes persist until you quit DigitalCD.
    Clicking Save does the same, and also stores your choices so that they
    are reloaded the next time DigitalCD is run.


                               Choices: Sections list
                               

      Skins    Alter the appearance of the control panels.
      Players  Adjust player behaviour.
      Mixing   Sound mixing options.
       Stereo  Sound stereo positionning.
       Equalizer    Sound frequency equalizer.
      Icon bar Behaviour of the DigitalCD icon.
      Plug-ins Sound visualisation plug-in selection and configuration.
       Samplers     Sound visualisation sampling options.
      Files    File loading and replay options.
       Filetypes    Filetype to driver mappings.
      Drivers   
       AMPlayer     AMPlayer module configuration.
       CDFS    CD player options and CD drive configuration.
        AcornCD     Download CD descriptions from the net.
       DiskSample   DiskSample module configuration.
       PlayIt  PlayIt module configuration.
       TimPlayer    TimPlayer module configuration.
      Internet Internet radio configuration.


                                    Choices: Skins
                                    

        Skins provide an 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 or use the arrows to browse through the
        list.

        If you install extra skins while DigitalCD is active, open the list
        with ADJUST to refresh the list.

        +   Single panel mode forces the reuse of the same window for every
            player (Files, Radios, CDs, Samplers).

        +   Treat 'Remove' as 'Never play' lets the Remove track command set
            the current track's Never play option instead of removing the
            current track from its playlist.


                                   Choices: Players
                                   

        +   Auto start main playlist at startup tells DigitalCD to
            immediately start playing the main playlist after startup.

        +   Remember position in playlist saves the last played position when
            leaving DigitalCD in order to be able to restart from the same
            position in the next session.

        +   Auto start playing new CDs in drives tells DigitalCD to
            immediately start playing any new CD inserted in a CD drive (but
            only if the corresponding control panel is open).

        +   Intro scan length is the number of seconds a track will play
            before moving onto the next track when the Intro scan mode is
            active.

        +   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.

        +   Lock CD database and playlists disables every feature for
            modifying the playlists and CD database so that you can safely
            put the player into the hands of less experienced parents,
            siblings or children.

        +   Reshuffle tracks when playlist loops works only when shuffle mode
            is active. When the playlist loops i.e. when the player is about
            to replay the first track it played, the playlist will be
            reshuffled to avoid playing the tracks in the same order as
            before.

        +   Pre-load next track opens the next track in memory when the
            current track is nearly played so that the next track is ready to
            play when the current track finishes. This reduces the silence
            gaps between the tracks to a minimum. Pay attention that it
            increases memory usage and that pre-loading is not always
            possible as the modules DigitalCD uses to play certain filetypes
            accept ony a single open file at a time.


                                   Choices: Mixing
                                   

        The options described below only affect sounds played through the
        internal sound card of your machine but not sounds produced by other
        hardware (CD drives or MIDI cards). Some options are also ignored by
        the drivers used to play some type of streams (files/radios).

        +   The mixing frequency is the rate at which the player 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. Note however that for compressed
            streams like MP3, the decompression of the stream is by far the
            most consuming task. 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
            decoders without 16-bit support.

            You may choose to use the specified frequency but you can also
            use a multiple of the track's sample rate. The later mode reduces
            the distortion introduced by playing the track's sample rate at
            an other rate (assumes that the sound card performs a decent
            digital to analog conversion at all the frequencies that the card
            supports). If the track's sample rate has no match in the card's
            frequency list, the nearest frequency is used. Also, if the track
            has no sampling rate (Tracker files, ...) the specified frequency
            is used.

        +   The DMA sound buffer size is the size, in number of samples, of
            the buffer that is filled during each sound buffer filling
            interrupt.

            The sound monitoring system used for sound visualisation plug-ins
            cannot track more than 100 sound buffer fillings per second and
            so it is better to use a size of 1024 to drop the filling
            frequency and avoid inconsistencies in displayed wave buffers or
            frequency spectrums.

            In case of incompatibility with other applications, use the safe
            size of 208.

        +   Set Interpolation if you wish the drivers to perform a linear
            interpolation between the values of samples of a lower frequency
            than the mixing frequency (the output becomes less metallic).
            Turning this option off on older machines can save some valuable
            processing power.

        +   Set Volume ramping so that the drivers use a short volume ramp at
            the start of every note instead of jumping directly from one note
            volume to another, muting some of the pops and clicks produced
            this way.

        +   Ignore system volume tells DigitalCD not to take the system sound
            volume into account so that a volume of 100% in DigitalCD
            corresponds to the maximal volume possible on the machine when
            normally the volume of 100% in DigitalCD corresponds to the
            system sound volume (value configured with the volume bar in the
            Sound section of the system's configuration or modified by the
            CLI command *volume).


                               Choices: Mixing, Stereo
                               

        The options described below only affect sounds played through the
        internal sound card of your machine but not sounds produced by other
        hardware (CD drives or MIDI cards). Some options are also ignored by
        the drivers used to play some type of streams (files/radios).

        +   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.

        Note: as a shortcut, clicking on the numbers below the bars will move
        the slider position directly to the corresponding value.


                                  Choices: Equalizer
                                  

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

        Once you are pleased with a set of settings just enter its name in
        the writable icon and click Save. The set is now saved and will
        appear in the menu associated to the popup icon at the right of the
        writable icon. You are now free to experiment with different settings
        and save the best ones. To recall a saved set just choose it from the
        menu.

        To delete an unwanted set choose it from the menu and click Delete.


                                  Choices: Icon bar
                                  

        This window defines which windows are opened by clicking on the
        DigitalCD icon on the icon bar.

        Choose for each variant of SELECT and ADJUST (alone or by pressing
        the Shift or Ctrl key at the same time) one of the windows from the
        list.


                                  Choices: Plug-ins
                                  

        Plug-ins provide desktop (windowed) or full-screen music driven
        animations. Plug-ins can only be started while playing data for which
        DigitalCD can sample the sound produced, so you may need to check if
        the correct sampler is setup first.

        +   While playing, you can start a full-screen plug-in (only one can
            work at a time) or a combination of several desktop plug-ins. So,
            you have either to set the Full-screen plug-in option and select
            a full-screen plug-in from the list, or to set the Desktop
            plug-ins option, browse the list of desktop plug-ins and
            enable/disable each of them in turn.

            In either case, click on the Info icon to obtain info on a
            plug-in, and click on Setup to configure it.

        +   When the option Auto-start with track is active the selected
            plug-ins will be started automatically when you start to play
            tracks. At any other time you will have to start them from the
            control panel.

        +   The Rescale with track volume multiplier option affects the
            rendering of visualisation plug-ins. The samples provided to the
            plug-in are indeed rescaled with regard to the main volume to
            provide the same rendering independently of the volume you are
            using. However, one must not forget that each track in a list
            benefits from a relative volume which could or not be taken into
            account when rescaling the samples.

            In general, it is better to leave this option inactive because
            the samples are then proportional to the relative volume whose
            goal is precisely to bring the tracks that are too quiet or too
            noisy to the same level as the other ones. A relative volume
            higher than 100% may however amplify the rescaled samples off
            limits and cause a visual distortion, so one may prefer to
            activate the option to prevent the problem.


                                  Choices: Samplers
                                  

        This section lets you define which sampling driver the DCDUtils
        module is going to use in order to feed visualisation plug-ins with
        samples of the played sounds.

        The sampling driver to use depends on what you are currently playing.
        Files and Internet radios are usually played through the more or less
        interceptable buffers of the SoundDMA module with the notable
        exception of MIDI files. Unless possessing a software MIDI
        synthesizer (such as !Synth from ESP) theses are played by a special
        hardware card. Finally, Audio CDs are played by the hardware present
        in the drive itself.

        In every case when the SoundDMA buffers are not used, samples of the
        sound can only be obtained using special hardware compatible with the
        API of the module SoundDriver.

        In consequence you should configure each of the following targets:

           Files or radio Files of every type except MIDI, Internet radio.
           MIDI File of type MIDI.
           CD drive 0 through n     Each of the CD drive in your machine.

        to use one of the following drivers:

           None Nothing is sampled (and no plug-in can be started).
           SoundDMA  Extracts sample data from the SoundDMA buffers.
           Any SoundDriver compatible driver present when DigitalCD is
            started (or more exactly when the DCDUtils module is started).

        When you choose a SoundDriver compatible driver you need to specify
        the configuration of that driver, namely: the sampling sources used,
        the kind of samples and the frequency of the sampling. It should be
        noted that, at the moment, DCDUtils only understands data provided as
        'stereo signed 16-bit'.


                                    Choices: Files
                                    

        +   Use filename as track title forces the playlists and the control
            panel's title bar to use the leafname of the file instead of the
            title of the music files.

        +   Unload driver when track ends will force the unloading of the RMA
            module used to play the track when that track is ended.

        +   Action when loading a file determines how DigitalCD handles
            double-clicking on a file or dropping files on certain parts of
            the application.

            The possible actions are:
                Ignore just ignores the action.
                Add to queue adds the file to the end of the file queue.
                Add to queue & Play adds the file to the end of the file
                 queue and, if nothing is playing, starts playing the content
                 of the file queue.
                Add to playlist just adds the file to the end of the main
                 playlist.
                Add to playlist & Play adds the file to the end of the main
                 playlist and, if nothing is playing, starts to play the main
                 playlist, beginning with the inserted file.

            In Addition:
                Add to ... also opens the playlist opens the playlist when
                 an Add to ... action is performed.


                                  Choices: Filetypes
                                  

        The list shows the filetypes loaded by DigitalCD and the name of the
        decoder used to play each of them. The section accepted filetypes
        will explain to you how to modify this list.


                                  Choices: AMPlayer
                                  

        +   The anti-shock buffer defines the size of the internal buffer
            used by AMPlayer to keep decoded sections of the track it is
            playing in memory. As the playing advances in the track this
            buffer is drained from the played sections while normally at the
            same time refilled with new decoded sections. Prolonged system
            activity (disc operations, SWIs) may however prevent refills
            occurring in time and cause pauses in the replay if the buffer
            becomes completely empty. A larger buffer will take more time to
            empty, which means there will be less risk of the sound played
            being interrupted.


                                    Choices: CDFS
                                    

        CD Drives

        Audio CDs can be played in two different modes: either the computer
        retrieves the "data" corresponding to the audio and send it to the
        sound system of the machine (in the same way as it would play a WAVE
        file) or it asks the drive to play the audio directly and send the
        output to one of the output connector of the drive (digital I2S or
        analog stereo jack).

        Both modes are not always possible: old drives do not support the
        data retrieval of audio, your computer may not have an I2S connector
        to to mix in the drives's audio and send it to it's own output
        connectors, and some recent drives don't even present output
        connectors. Also even when you can fallback on the second mode, some
        drives have issues which need to be worked around.

        It is thus important to configure the proprer playing mode of the
        drive.

        The following options are configurable separately for each CD drive
        of your machine.

        +   Mode

            use CD_ReadAudio to retrieve the CD audio data and replay it on
            the computer's sound system. Pro: you get all the mixer options
            (equalizer, stereo control). Con: it uses some CPU and is not
            compatible with older CD drives.

            use CD_PlayAudio to request the drive to send the sound to one of
            the drive's output connector. Pro: no CPU usage. Con: requires a
            link from drive's connector (which may not even exist) to the
            speakers or to the sound card of the machine.

            use CD_PlayAudio (track by track) to do as CD_PlayAudio, but
            requesting to play only till end of track, not the end of the
            disc. Pro: it is compatible with more drives. Con: it leaves
            short gaps of silence between tracks.

            use CD_PlayTrack which is an older method than CD_ReadAudio. Pro:
            it is compatible with more drives. Con: it plays from track start
            to end with no possibility to jump within the track.

        +   CDFS driver with 150 frames bug

            Some versions of CDFSSoftxxxx modules contain a bug in their code
            which is responsible for a 150 frames (2 seconds) difference
            between the specification of a new replay position and the value
            returned by the interface when asking the current position on the
            CD.

            How can you tell if you have this problem? Well, start playing a
            CD and use the Rewind and Forward buttons: they should normally
            move you 1 second backwards or forward in the track, but if this
            is not the case (e.g. the Forward button moves you backward in
            the track, etc), turn the switch on.

        +   Nudge CD size by copes with some versions of CDFSSoftxxxx modules
            returning CD sizes which differ by 1 frame. As a result different
            drives may report different identifications (see the *Whichdisc
            command) for the same CD and DigitalCD doesn't find its
            description in the CD database. When this happens, note the
            difference in CD identification reported by the CD control panel
            and the identification stored in the CD database then adjust here
            the correction to apply for this drive.

        CD Player

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

        +   Don't show drive number allows you to hide the CD drive number "<
            x >" displayed with the title/author of the CD.


                                   Choices: AcornCD
                                   

        Manually typing the description of your CDs is not required, a number
        of CDDB (acronym for CD Database) servers exists on the Internet and
        contain the description (name and artist of the album, title of each
        track) of most of the CDs existing today.

        The AcornCD application can be used to read the characteristics of
        the CD in your drive, grab its description on one of these servers
        and provide it to DigitalCD.

        +   The AcornCD option authorizes DigitalCD to ask AcornCD for the
            description of any not yet identified CD present in your drive.

        +   Allow remote connection tells AcornCD that it may connect to
            Internet 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 AcornCD
            are taking place.

        +   AcornCD path should contain the path of AcornCD on your machine
            so that DigitalCD may start the application in case AcornCD is
            not yet running. Just drag the !AcornCD icon from the directory
            display to the entry box to fill it.


                                 Choices: DiskSample
                                 

        +   Input buffer size is the size of the internal buffer used by
            DiskSample decoders to keep the next sections to decode of the
            track it is playing in memory. As the playing advances this
            buffer is drained from the decoded sections while normally at the
            same time refilled with the new sections to decode. Prolonged
            system activity (disc operations, SWIs) may prevent refills
            occurring in time and cause pauses in the replay if the buffer
            becomes completely empty. A larger buffer will take more time to
            empty and as such will be less subject to interruptions in the
            sound.

        +   Output buffer size is the size of the internal buffer used by
            DiskSample decoders to keep decoded sections of the track it is
            playing in memory. As the playing advances this buffer is drained
            from the played sections while normally at the same time refilled
            with new decoded sections. Prolonged system activity (disc
            operations, SWIs) may prevent refills occurring in time and cause
            pauses in the replay if the buffer becomes completely empty. A
            larger buffer will take more time to empty and as such will be
            less subject to interruptions in the sound.

        +   Free volume is related to the mixer's Automatic Gain Control
            procedure. This one fits the volume back into the desired output
            level when the equalizer is active with the side effect of a
            reduction in the sound's dynamics. The Free volume option let the
            AGC limit only to full scale volume giving you back some dynamics
            if you reduce the playing volume of the track.

        +   Enable interrupts allows other interrupt based processes like
            Internet to operate while filling sound buffers (which can be a
            slow process while mixing too many channels or while the
            equalizer is active). The drawback of this option is that cuts in
            the sound may occur if these other processes (like disc activity)
            take too much time.


                                   Choices: PlayIt
                                   

        +   Buffer size is the size of the internal buffer used by PlayIt to
            keep sections of the sample file it is playing in memory. As the
            playing advances in the track this buffer is drained from the
            played sections while normally at the same time refilled with the
            next sample sections. Prolonged system activity (disc operations,
            SWIs) may prevent refills occurring in time and cause pauses in
            the replay if the buffer becomes completely empty. A larger
            buffer will take more time to empty and as such will be less
            subject to interruptions in the sound.

        +   Selecting 'Interpret unknown format as' forces PlayIt to
            interpret any track of a format which is unknown to it using the
            parameters (format, frequency and channels) of your choice
            instead of returning an error. Note that only the type of files
            associated to PlayIt (see configuration of accepted filetypes)
            will be subject to such an interpretation.


                                  Choices: TimPlayer
                                  

        +   Polyphony sets an upper limit to the number of playing notes. The
            default is 64 but can be increased to 128 but don't get carried
            away (RPCEmu for example starts stuttering when the load is too
            high).

        +   Free volume is related to the mixer's Automatic Gain Control
            procedure. This one fits the volume back into the desired output
            level when the equalizer is active (or when the internal
            pre-amplification, function of the number of channels, is too
            great) with the side effect of a reduction in the sound's
            dynamics. The Free volume option let the AGC limit only to full
            scale volume giving you back some dynamics if you reduce the
            playing volume of the track.

        +   Enable interrupts allows other interrupt based processes like
            Internet to operate while filling sound buffers (which can be a
            slow process while mixing too many channels or while the
            equalizer is active). The drawback of this option is that cuts in
            the sound may occur if these other processes (like disc activity)
            take too much time.


                                  Choices: Internet
                                  

        +   Use proxy tells DigitalCD if it should attempt to retrieve HTTP
            streams from Internet radios by going through the given proxy
            URL. The proxy URL should be to typed in the form
            http://[\user[:<password>]@]<host>[:<port>]/ where items between
            [] are optional and items between <> must be replaced by the
            relevant text, for example http://proxy.skynet.be:8080/.

        +   Select Request Icy metadata to request metadata on the titles
            played from Shoutcast compatible servers.

            It should be noted that this metadata is inserted at regular
            intervals within the MP3 stream and that these intervals are
            defined in the returned HTTP headers of the streams. If for some
            reason those cannot be retrieved it becomes impossible to remove
            the metadata before passing the stream to the MP3 decoder,
            leading to MP3 decoding problems and resulting in recurring
            audible effects.

            One would think that the above problem should not arise however
            Shoutcast servers don't return valid HTTP headers and this causes
            problems for any machine in the transmission chain between the
            server and you which manipulates these headers. The most common
            cases are HTTP proxies who replace these headers by default ones.

            DigitalCD will always ignore this option when a proxy is
            specified but proxies may not be the only cause for similar
            problems so if you experience recurring sound effects you may try
            to deactivate this option to see if it makes a difference.

        +   Select Request Audiocast metadata to request metadata on the
            titles played from Audiocast compatible servers (like Icecast
            version 1).

            It should be noted that this metadata is retrieved by listening
            on a separate UDP port and usually blocked by firewalls at both
            the sending and receiving sides. As such servers usually support
            Icy metadata it is usually best to leave this option unselected.

        +   Buffer let you define the minimal amount of decoded data to
            accumulate (buffer size permitting) before starting to replay the
            sound. The purpose of this reserve is to prevent as much as
            possible the sound to be broken by disruptions in the flow of
            data from the Internet.


                              Visualisation plug-ins
                              

    Visualisation plug-ins are multi-tasking applications used by DigitalCD
    to display real-time graphical representations of sounds. They are
    launched from a player's control panel by choosing Start plug-ins from
    the Misc submenu or by pressing Ctrl+K. Note that a track must be playing
    before a plug-in can be started, and an appropriate sound sampler must be
    available.

    Plug-ins are configured in the Plug-ins section of the Choices window. If
    no plug-ins have been configured, pressing Ctrl+K or selecting Start
    plug-ins will have no effect.

    Plug-ins come in two types:
       Full-screen plug-ins take over the whole screen, and may even change
        the resolution and colour depth while they are running. These
        plug-ins will redirect all key presses which are not of interest to
        them to the player, which means you can continue to control the
        player via its shortcuts.
       Desktop plug-ins run in the desktop environment, and often attach
        themselves to the borders of the player's control panel. You can use
        several desktop plug-ins at the same time.

    Installing plug-ins

    Plug-ins should be installed in the resources directory. Full-screen
    plug-ins should be copied into !DCDRes.PlugIns.FullScreen and desktop
    plug-ins into !DCDRes.PlugIns.Desktop.

    When upgrading plug-ins, it is usual to delete the old version before
    installing the new one, but you should always check the installation
    instructions that come with the plug-in.

                            Creating your own plug-ins
                                 Troubleshooting


                            Visualisation: Sound capture
                            

      The decoders used by DigitalCD to play tracks all decode digital
      information which is at some point converted by the mixing hardware in
      your machine in the analogue signal that is directed to the internal
      speakers or to the stereo jack socket at the back of the computer.
      These decoders can either, fill the SoundDMA buffers whose content is
      fed to the mixing hardware by the VIDC chip on the motherboard, or use
      third party hardware which does the job.

      In order to let plug-ins display the sounds produced by the tracks,
      DigitalCD must feed them with a digital representation of those sounds
      and so must be able to sample them. And this is where the problem lies:
      PCs come with sound cards equipped with the sampling hardware required
      to sample the different sources of sound fed to the mixer and generic
      support for them in the operating system, but Acorn computers only ever
      came with support for internally produced sounds.

      The consequences are that DigitalCD can sample the contents of internal
      SoundDMA buffers and that is all unless you have installed third party
      hardware able to do both the mixing and sampling. And then DigitalCD
      must be able to access the sampler without any help from RISC OS, using
      the manufacturer's API.

      What kind of tracks can then be visualized by DigitalCD?

      Basically all files are decoded internally and so can be visualized.
      There is one exception, MIDI files. Those are normally decoded by a
      specialized hardware card (unless you use a software synthesizer such
      as !Synth). 

      For MIDI and CDs, DigitalCD supports hardware cards which can be
      accessed through the only attempt at a standard interface I know of:
      SoundDriver. In practice, I think it means support is restricted to the
      rare owners of the DMI card (not that there are many other available
      cards around). As a bonus if they use the Samplers player, owners of
      these cards will also be able to monitor all the other sound sources
      available though the card like, line-in or microphone.

       Mapping tracks types and Samplers 
       Ensuring that SoundDriver works 


                  Visualisation: Capture with the SoundDriver module
                  

        For those who don't know, ESP (Expressive Software Projects) has
        defined a standard API for sound sampling in the form of the
        SoundDriver module to which drivers for different sound capture
        hardware register themselves (actually you will only find drivers for
        the DMI card). I don't own the appropriate hardware, but the
        SharedSound module provides a driver to capture sound produced
        internally by the machine, so ESP kindly provided me with a version
        of the SoundDriver module so that I could use the interface to allow
        DigitalCD's visualisation plug-ins to display sound produced by CDs
        or MIDI hardware.

        Before use, if the SoundDriver module and its associated drivers are
        not yet loaded into memory (not in the ROM of an extension card, nor
        loaded in memory during the startup of the machine), please:

           Exit any application that uses the DCDUtils module such as
            DigitalCD and some independent sound animations (Spectrum,
            FireComet, ...).
           Kill the DCDUtils module if present in memory (through a *RMKill
            DCDUtils.
           Start the SoundDriver module and its associated drivers.
           Start DigitalCD.

        During the first use you must configure DigitalCD to tell him how to
        sample the various kinds of soundtracks used by DigitalCD. To do so:
           Open the Choices window and go to the Visualisation->Samplers
            section. 
           Associate the 'SoundDMA' driver with the 'Files' target (and to
            'MIDI' if you are using the !Synth MIDI software synthesis).
           Associate the 'None' driver for any kind of soundtrack for which
            you have no possibility to capture the sound.
           Associate the appropriate driver for the remaining targets, then
            adjust the left and right sources, the sample type (only signed
            16-bit is supported at the moment) and the sample rate (probably
            44100 Hz). 
           Save the choices.

        You should now be able to start plug-ins for any played track from a
        source for which a driver is defined.

        If you which to visualize sound not played by DigitalCD itself such
        as line-in, open the sound monitor player, select the driver to use
        from the list of tracks and start the plug-ins.

        Known problems:

           Only stereo signed 16-bit sampling is supported.
           SWI SoundDriver_Record produces textual output on screen (I just
            hope I received a debug version of the module from ESP and that
            this text is normally not shown).


                                 Plug-ins: Creation
                                 

      Plug-ins are multitasking applications stored either in
      !DCDRes.PlugIns.Desktop if they run in windows on the desktop, or in
      !DCDRes.PlugIns.FullScreen if they take over the screen.

      The plug-in like other applications is a directory containing all the
      files it requires to run but, unless giving it the capability to run
      independently from DigitalCD (like !Spectrum), there is no need to
      prefix the directory with "!" nor to provide !Boot and !Sprites files.

      The directory may contain any files you wish but 3 of these files
      (!Run, !Help and !SrvSetup) have a special meaning. DigitalCD will use
      the Filer_Run command to start each of those.

                             Files with special meaning
                              Writing the main program


                         Plug-ins: Files with special meaning
                         

           !Run is a mandatory file and is used to start the plug-in. It's
            the usual Obey file where you initialize a few variables, define
            the wimpslot size and start the main program. DigitalCD will
            Filer_Run this file with as single parameter a player handle that
            you will need to pass onto the main program (See Writing the main
            program for more details).

           !Help is an optional file and is used to provide information on
            the plug-in. Usually it's a simple text file.

           !SvrSetup is optional too and will be used to configure the
            plug-in. It is most likely form is not a file but an application
            directory (without !Boot or !Sprites files).

        You may have noticed that I used the same name convention as for
        screen savers. It was intended in that was just in case you decide to
        write a plug-in which can also work as screen saver.


                          Plug-ins: Writing the main program
                          

        The main program is a multitasking application which receives at
        least one parameter from your !Run file. The parameter is a player
        handle for the DCDUtils module that you will have to use to register
        and unregister your plug-in and to retrieve information like sound
        buffers or the player's current track title.

        At this point you can either:

                Start to read carefully the DCDUtils manual which explains
                 the protocol and rules to follow by a plug-in as well as a
                 complete description of the DCDUtils SWIs.
                Use the !DigitalCD.RMStore.DCDLib BASIC library that does
                 all the 'dirty work' required to write a fullscreen plug-in
                 leaving you with the only task of filling screen frames and
                 interpreting wimp key presses. Audio16 and FireComet are
                 examples of plug-ins that use this library. Note that
                 programs written with the DCDLib may also run independently
                 from DigitalCD (as long as you don't forget to RMEnsure the
                 DCDUtils module).
            Look at the C sources included within the
            !DigitalCD.Copy.PowerBars windowed plug-in.

        Happy coding!


                                       List
                                       

    A list is a simple representation of data, displaying one or more columns
    of selectable elements. Lists come in two kinds:
       Single-selection lists are lists where only one element can be
        selected at a time.
       Multiple-selection lists are lists where several elements can be
        selected at once.

     Navigation with the keyboard
     Selection with the keyboard
     Selection/Edition with the mouse


                         List: Navigation with the keyboard
                         

      If the list has not the focus, clicking in the list gives it the focus
      and positions the cursor presented in the form of a dotted box
      surrounding the element's title. In the case of a click with SELECT on
      an element, this element is selected in place of any pre-existing
      selection. In the other cases the cursor will simply be positioned
      again in its last known position.

      Using the Up/Down arrows (possibly combined with Shift or Ctrl) or Page
      Up/Down lets you browse through the list just like in any document. In
      normal mode you will notice as the cursor moves that the selection is
      reset each time to the element on which the cursor is positioned, while
      in movement mode, the selection is not affected. Press Insert to switch
      between these two modes.


                     List: Selecting elements with the keyboard
                     

      We are going to proceed from an example attempt to select a set of
      elements forming a series of non-contiguous blocks.

      First we are going to select a block of elements containing all the
      desired elements. Position the cursor to the first element of the first
      block to select, press Shift+Insert to mark the start of the selection,
      move to the last element to select in the block and press Shift+Insert
      again to mark the end of the selection. We have selected our first
      block.

      Now we are going to deselect a block within the first one. Knowing that
      moving the cursor normally resets the selection we must press Insert to
      toggle from the normal mode to a mode where the cursor's movements do
      not affect the selection.

      You can now move the cursor to the start of the block to deselect.
      Press Ctrl+Insert, move to the end of the block and press Ctrl+Insert
      again. This will invert the selection state of the elements within the
      second block and thus in our case removes the elements from the
      selection. The same technique can be used as well to add elements to
      the selection.

      To compare with selections made with the mouse, Shift+Insert acts as
      selecting with SELECT and Ctrl+Insert acts as selecting with ADJUST.

      Finally, you can also invert the selection state of the element
      designated by the cursor by pressing Space.


                  List: Selecting/Editing elements with the mouse
                  

      Clicking SELECT while pressing the Alt key will allow you to edit the
      textual parts(s) of modifiable elements.

      Selection and dragging of elements with the mouse is modelled loosely
      after the Filer.

      For reference, in the filer you drag a box with SELECT around the files
      to select then click or drag a box with ADJUST to invert the state of
      files without clearing the existing selection. Once this is done you
      move the pointer over a selected element and press SELECT to drag the
      selection around.

      In a list you drag with SELECT from the first element to the last
      element to select, then to invert the state of elements without
      clearing the existing selection you click or drag with ADJUST. While
      dragging, positioning the pointer within the window, near its border,
      will force the window to scroll. Once this is done you move the pointer
      over a selected element and press SELECT to drag the selection around.

      What differs from the Filer is that you cannot click between elements.
      This means that you cannot select and drag a previously unselected
      element in a single operation. You have to click on the element,
      release the button to mark the end of the selection process and then
      press the button again to start dragging it.


                                    Tree view
                                    

    A tree view is a hierarchical representation which organizes data into
    groups and possibly sub-groups. Each group may contain one or more
    elements. An element can either be simple data or a lower-level
    sub-group. Sub-groups can contain sub-groups of their own, and so on.

    In such views several terms are often used:
       Parent: The group containing the element in question.
       Siblings: Other elements having the same parent group as the element
        in question.
       Children: If the element is a group, the elements contained in that
        group. If the element is not a group, it cannot have any children.

     Navigation with the keyboard
     Show/Hide the content of a group

    The selection/edition mechanisms are identical to those a list.


                      Tree view: Navigation with the keyboard
                      

      If the view has not the focus, clicking in the view gives it the focus
      and positions the cursor presented in the form of a dotted box
      surrounding the element. In the case of a click with SELECT on an
      element, this element is selected in place of any pre-existing
      selection, in the other cases the cursor will simply be positioned
      again in its last known position.

      Using the Up/Down arrows (possibly combined with Shift or Ctrl) or Page
      Up/Down lets you browse through the view just like in any document. In
      normal mode you will notice as the cursor moves that the selection is
      reset each time to the element on which the cursor is positioned, while
      in movement mode, the selection is not affected. Press Insert to switch
      between these two modes.

      The Left/Right arrows allow you to move directly between sibling
      elements and bypass their children.

      Shift+Left allows you to move directly to the parent of the current
      element.

      Shift+Right allows you to move directly to the sibling which follows
      the parent of the current element.


                    Tree view: Show/hide the content of a group 
                    

      In most cases the content of group is not visible by default, you have
      to click SELECT on the little box with + that stands before the name of
      the group (or press Return) in order to unfold the group and show its
      content. The + then turns into a - and you will just have to click
      SELECT on this - to fold again the group and hide its content.

      You will notice that by clicking SELECT on the + only a single level of
      the arborescence is unfolded, the content of the sub-groups remain
      invisible. To unfold in a single operation the whole arborescence,
      press Ctrl while clicking SELECT (or press Ctrl+Return).

      Finally, know that when you hide the content of a group, the folding
      state of the whole arborescence it contains is retained. If you then
      click not SELECT but ADJUST on the + (or press Shift+Return) the
      arborescence will be shown again as in the same state as before being
      hidden.


                                 Troubleshooting
                                 

       Starting DigitalCD
       CD drives
       File playing
       Internet radio
       Visualisation plug-ins
       Other problems


                        Troubleshooting: Starting DigitalCD
                        

      1)  How do I force DigitalCD to start when I double-click a file?

      By default, DigitalCD only responds to file type &155 (FileList). This
      is to prevent DigitalCD taking priority over sound file editors.

      To alter this behaviour, refer to the accepted file types and
      configuration sections, and ensure that DigitalCD is seen by the Filer
      when the computer boots.

      2)  How do I include DigitalCD in the boot sequence of the machine so
          that I don't get an error saying "Please locate !DCDRes"?

      When DigitalCD boots, the !DCDRes.Setup file is scanned to determine
      which music filetypes it should claim, if any. (See above). This means
      DigitalCD needs to know the location of the !DCDRes folder at boot
      time. You should either:

         Make sure !DCDRes is listed before !DigitalCD in the list of
          applications to boot of your boot sequence.

         Ensure that !DCDRes is in a place where DigitalCD can find it:
          either in the same directory as !DigitalCD, or in Boot:Resources.

      3)  DigitalCD freezes the system or don't work correctly when started
          during the boot sequence of RISC OS.

      Please refer to question 2 of the CD drives troubleshooting section.


                             Troubleshooting: CD drives
                             

      1)  The CD player seems to play normally but I hear no sound.

      CD drives produce sound independently from the computer's sound system.
      There are three ways to listen to the sound produced:

         If the drive allows it (USB drives and other recent drives), read
          the CD audio data and replay it on the computer's sound system.
          Stop any CD that is playing and open the Drivers/CDFS section of
          the Choices window. Select the drive number corresponding to the
          faulty CD drive, set the mode to 'use CD_ReadAudio', then click
          Save or Set. You can then resume CD playback.
         Plug your headphones/speakers into the 3.5mm stereo jack socket in
          the front panel of the CD drive.
         Use a cable to connect the I2S plug on the back of the CD drive to
          a mixer card. The mixer card's function is to mix the sound
          produced by the computer's sound system with any other external
          source(s) and send the resulting sound to the 3.5mm stereo jack
          plug at the back of the computer. For those who have upgraded their
          old RISC PC motherboard's 8-bit sound system with a Mozart card I
          can confirm there is such a mixer on the card, but for everyone
          else I can only recommend that you speak to your local RISC OS
          dealer.

      2)  DigitalCD freezes the system or doesn't work correctly when started
          from the RISC OS boot sequence.

      I don't know the exact cause of this problem, except that until the
      desktop is completely initialised some of the CD calls made by
      DigitalCD don't work properly on some machines. For some, the call
      hangs the system, for others it reports that the drive is empty even
      when there is a CD in the drive.

      I have been told that the false 'drive is empty' reports can be avoided
      by ensuring that there is no CD in the drive when booting.

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

      Stop any CD that is playing and open the Drivers/CDFS section of the
      Choices window. Select the drive number corresponding to the faulty CD
      drive, check or uncheck the 'CDFS driver with 150 frames bug' option,
      then click Save or Set. You can then resume CD playback. This bug is
      present for nearly all SCSI drives and for IDE drives controlled by old
      versions of the CDFSSoftAtapi driver.

      4)  The CD player skips every track or doesn't work at all.

      Stop any CD that is playing and open the Drivers/CDFS section of the
      Choices window. Select the drive number corresponding to the faulty CD
      drive and select the 'Play using CD_PlayTrack SWI' option. Click Save
      or Set, and resume CD playback. The CD_PlayTrack SWI seems to work with
      more CD drives than the CD_PlayAudio SWI, but using CD_PlayTrack means
      you can't alter the playback position within a track.

      If this doesn't work, I don't know. I am afraid that on the one hand
      CDFS and the related CDFSSoftxxx modules are not of the finest quality,
      and on the other hand many drives do not conform to the standards they
      claim to. This may lead to strange problems such as CDFS reporting that
      the drive is not playing even while it is actually playing an audio
      track.

      To collect more information I have set up a system which logs the CDFS
      calls made by DigitalCD into a file called 'Log'. This file will appear
      in the same directory as the DigitalCD application. To activate
      logging, you need to modify the !DigitalCD.!Run. Change

      Set DigitalCD$Logging 0

      into

      Set DigitalCD$Logging 1

      When you restart DigitalCD, attempt to play a CD and send me the
      generated Log file (or look at the file yourself if you have enough
      knowledge of the CDFS SWIs).

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

      The most probable cause is that the file !DCDRes.CDs is
      write-protected. You may be running !DigitalCD and !DCDRes (see
      Resources management) from a read-only archive, filing system or media
      (such as a CD). Note that SparkFS 1.33 and earlier may cause problems
      when attempting to write to a read-only archive.


                            Troubleshooting: Music files
                            

      1)  DigitalCD is not started when I double-click on a music file.

      By default, DigitalCD only responds to file type &155 (FileList). This
      is to prevent DigitalCD taking priority over sound file editors.

      To alter this behaviour, refer to the accepted file types and
      configuration sections, and ensure that DigitalCD is seen by the Filer
      when the computer boots.

      2)  DigitalCD ignores a file when I drop it on one of its playlists.

      DigitalCD only accepts the files whose RISC OS filetype is defined in
      one of its configuration files. The reason for this is quite simple,
      many of the formats supported by DigitalCD don't define clear headers
      which would allow identifying them; the use of the correct filetype is
      then the only way to select the appropriate driver/loader for the
      decoding of the file.

      If you are making an exclusive use of a given RISC OS filetype for a
      specific type of files which one of the DigitalCD driver is capable of
      reading, refer to the page Accepted filetypes, configuration for
      instructions on how to add it to the list.

      3)  When playing files DigitalCD seems to replay them but I don't hear
          anything or the sound is very quiet.

      Normally the volume of 100% in DigitalCD corresponds to the system
      sound volume (value configured with the volume bar in the Sound section
      of the system's configuration or modified by the CLI command *volume).
      Correct the system sound volume if the value is too low or set the
      'Ignore system volume' option in the Choices window, section Players.


                          Troubleshooting: Internet access
                          

      1)  No entry is inserted in DigitalCD's playlist when I drop Internet
          radio lists (.m3u or .pls files) from my Internet browser to
          DigitalCD.

      In the first place, check that you have dropped the list of radios to
      the appropriate playlist of DigitalCD, some like the file queue or
      directory lists don't accept Internet radios.

      If it still happens that no entries are inserted, save these radio
      lists instead on your harddisk, and:
         check that .m3u files have filetype AA7 and .pls files AA8. If not,
          adapt their filetypes and drop the updated files onto one of the
          DigitalCD's playlist window.
         check that the contents of the file is correct, which means for
          .m3u files a simple url and for .pls file a first line with
          "[playlist]" and a least a line with "File<nr>=<url>".

      2)  DigitalCD fails to establish the connection to the Internet radio.

      To be able to listen to Internet radios some configuration operations
      both of your machine and DigitalCD are required. They are described
      here; check that you have followed them correctly.

      If the problem still happens, show the properties of the radio (select
      the radio in the playlist, open the playlist's menu and choose
      Properties from the Internet radios submenu). Copy the URL of the radio
      in your Internet browser and attempt the connection. If it is working
      (if the browser proposes to save or open what it thinks is a file)
      check the DigitalCD preferences against those of your browser. In the
      other case, well, the radio is simply not reachable.

      3)  The connection to the Internet radio is made, the modem shows that
          DigitalCD downloads data but DigitalCD doesn't play anything and
          its timer doesn't change.

      I have noticed that some radios like France Inter, when down, continue
      to send Ogg Vorbis streams made only of repeated ogg headers. This
      means that DigitalCD will waste its time downloading MBs of data while
      there isn't a single sample to decode (the elapsed time will remain at
      zero forever).

      4)  Internet performance is degraded while playing MPEG Audio or Ogg
          Vorbis files (through DiskSample).

      The degradation is caused by the time spent by Diskample in the
      SoundDMA buffer filling interrupt, which stops the processing of other
      interrupts (serial port, network, ...). This blocking period may become
      important if too much channels are mixed of if the equalizer is active.
      Several solutions are possible:

         Don't use the Equalizer while accessing the Internet to drastically
          reduce the time spent to fill SoundDMA buffers.

         Open the Choices window, section Drivers/DiskSample, and activate
          the option Enable Interrupts. With this option enabled DiskSample
          will allow other interrupts to be serviced while filling the
          SounDMA, which solves the problem but may have the consequence of
          preventing the in time filling of the buffers and cause cuts in
          sound (for example while accessing discs).

      5)  Internet performance is degraded while playing tracker files (MOD,
          S3M, etc).

      The degradation, like above, is caused by the time spent by TimPlayer
      in the SoundDMA buffer filling interrupt, which stops the processing of
      other interrupts (serial port, network, ...). This blocking period may
      become important if too much channels are mixed of if the equalizer is
      active. As TimPlayer often mixes far more channels than DiskSample, the
      degradation may be far worse. Several solutions are possible:

         Don't use the Equalizer while accessing the Internet to drastically
          reduce the time spent to fill SoundDMA buffers.

         Open the Choices window, section Drivers/Timplayer, and activate
          the option Enable Interrupts. With this option enabled DiskSample
          will allow other interrupts to be serviced while filling the
          SounDMA, which solves the problem but may have the consequence of
          preventing the in time filling of the buffers and cause cuts in
          sound (for example while accessing discs).

          Be also aware that TimPlayer monitors the time spent to mix the
          played notes in the buffers and may decide to limit the number of
          notes played simultaneously (polyphony) if it can't do it in real
          time. This is to keep the machine responding to the user (there are
          a few 64 channels files around who would easily need more than 100%
          of the CPU even on StrongARM machines). If you enable the
          interrupts, the time spent by other interrupts serviced during that
          period will also counted in by TimPlayer and may then cause sharp
          drops in the note polyphony. In such case, pausing then un-pausing
          the track will restore the note polyphony to its default value.


                      Troubleshooting: Visualisation plug-ins
                      

      1)  The player is playing a track but the Start plug-in menu item
          remains greyed.

      The player will not allow starting sound visualisation for a track when
      it doesn't know how to capture the sound produce by that track. Before
      attempting visualisation you need first to open the Samplers section of
      the Choices window and setup the appropriate sound sampler to use for
      each kind of playable track. Note that on most RISC OS machines there
      is simply no way to capture sounds from CD tracks.

      2)  When I try to start the plug-in I get an error saying "Invalid
          screen mode".

      As the error says, the plug-in is attempting to use a screen mode not
      present on your machine. Open the Plug-ins section of the Choices
      window and click on the Info button below the selected full-screen
      plug-in. After reading the plug-in information, you will find out
      either that:

         The plug-in can be configured to use a different screen mode.

          So, in the choices window, click on the Setup button below the
          selected full-screen plug-in and follow the plug-in's documentation
          to select an appropriate screen mode.

         The plug-in use a specific screen mode which is not present in the
          monitor definition file (MDF) used by RISC OS to control your
          monitor.

          You will need to edit this MDF with the appropriate tool and define
          that screen mode in the MDF. If you can't figure out the correct
          parameters for the screen mode, which is bound to occur for low
          resolution screen modes as most LCD monitors don't support any
          screen mode below 640 x 480, you can always use the border method.

          Borders are just extra lines and extra pixels, usually of black
          colour, inserted by RISC OS around the display area so that the
          monitor sees a resolution 'display area + borders', while from the
          application's point of view the resolution is 'display area'. So,
          you just have to copy a larger mode definition and move the extra
          pixels in the display area to the borders while maintaining
          constant the resolution seen by the monitor. The drawback of this
          method is that image doesn't cover the whole surface of the monitor
          but it is still better than no image at all.

      3)  The plug-in starts but the display remains un-animated.

      DigitalCD must be attempting to capture sound using the wrong sound
      sampler. Open the Samplers section of the Choices window and setup the
      appropriate sound sampler to use for each kind of playable track. Note
      that on most RISC OS machines there is simply no way to capture sounds
      from CD tracks.


                      Troubleshooting: Miscellaneous problems
                      

      1)  When I start DigitalCD I keep getting the error message "The
          file/dir
      '<MP3$Dir>' doesn't exist or its access is denied". What's causing it?

      This happens when your main playlist contains a directory list which
      points to the default directory name '<MP3$Dir>'. When starting
      DigitalCD tries to scan the contents of directory lists and reports
      such an error message when the directory the list points to doesn't
      exist. Just remove that directory list or, if you are using it from
      time to time, edit its properties so that the list is not loaded at
      startup.

      2)  Clicking MENU on a playlist doesn't make the menu appear and after
          several attempts, DigitalCD crashes.

      I have identified the problem and it occurs because I keep waiting for
      an answer to a message I broadcast requesting info on the contents of
      the clipboard (to update the status of the 'Paste' menu entry). What
      happens is that the clipboard owner incorrectly sends the reply to
      another program, and so I don't exit my waiting loop because neither do
      I receive a reply nor does the system tell me that there is no reply.
      Locate the application that owns the clipboard and get a fixed version
      from its author.

      3)  When listening to music files the player sometimes interrupts for
          no apparent reason the current file and carries on to play 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 file (of type tracker) played contains an end of sequence
               marker or a jump to a backward position in the pattern
               sequence and so the file is considered to be composed of
               several sections. The patterns which follow in the sequence
               are either trials discarded from the final version, or the
               file is composed of several independent songs (probably for a
               game, Lemmings springs to my mind here).

               If you wish to listen to these sections, switch the repeat
               mode to 'loop on track' and while playing use the
               Rewind/Forward buttons to move to that part of the file.


                                    Appendices
                                    

    Address, homepage and mailing list
    Required external applications
    Upgrading from a previous version
    Updating you Mimemap file
    Format of files with type FileList (&155)
    Metadata extractors
    Resources management
    License
    Credits
    History


                         Address, homepage and mailing list
                         

              DigitalCD is maintained by Andr Timmermans

                                         fa044826@skynet.be

                         DigitalCD's homepage redirector is

                            http://www.riscos-digitalcd.net/

                              and currently points to

                        http://users.skynet.be/Andre.Timmermans/

       To subscribe to DigitalCD's mailing list send an email with a friendly
                                      word to

                          DigitalCD-subscribe@yahoogroups.com

       Subscription is subject to my approval (to avoid spam) and I often do
         not have time to check my email, so don't be surprised if it takes
               several days before you're added to the mailing list.


                               External applications
                               

         Rick Hudson's PlayIt version 1.67 or later should be installed on
          your system so that DigitalCD can play WAV and other sample files.

         DigitalCD can talk to version 0.19 or above of John Beranek's
          AcornCD application, provided you configure the AcornCD section in
          the Choices window correctly. CDDB stands for CD DataBase: it's a
          way for you to download information on a CD from the internet
          rather than typing it in for yourself. The CDDB client reads the
          characteristics of the CD in your drive and retrieves its
          description (album, track titles and other information) from one of
          the CDDB servers on the internet. The AcornCD home page is
          http://acorncd.sourceforge.net/.


                         Upgrading from a previous version
                         

      Upgrading from versions 2.44 or above

      When the new version of DigitalCD is started for the first time it will
      automatically erase from !DCDRes old versions of its default skin and
      plug-ins and create the new ones, the other resources will not be
      modified.

      The files !DCDRes.Setup and !DCDRes.Clues will not be touched to avoid
      overwriting your own settings. It could however be wise to check if the
      default versions in !DigitalCD.Copy does not contains any updates in
      the list of filetypes or clues sprites and to transpose these changes
      in your own versions.

      
      Upgrading from versions 2.41 to 2.43

      DigitalCD now stores skins, plug-ins, etc into the !DCDRes folder in
      order to allow easier upgrades in the future.

      To recover your old resources, move the following files and directories
      from the old version of !DigitalCD to !DCDRes:

              the file CDs (CD database)
              the file Setup (filetype vs decoder mapping)
              the directory Skins
              the directory Plugins

      
      Upgrading from versions before 2.41

      DigitalCD now stores skins, plug-ins, etc into the !DCDRes folder in
      order to allow easier upgrades in the future.

      To recover your old resources, move the following files and directories
      from the old version of !DigitalCD to !DCDRes:

              the file CDs (CD database)
              the file Setup (filetype vs decoder mapping)
              the directory Skins

      Move your plug-ins from the old !DigitalCD.PlugIns into
      !DCDRes.PlugIns.FullScreen with the exception of PowerBars for which a
      new version will be put by DigitalCD itself in !DCDRes.PlugIns.Desktop.


                             Updating the MimeMap file
                             

      The MimeMap file defines the mappings between mime content type
      (Internet), RISC OS/Mac file types and PC/Unix file extensions. Click
      here to open the file in your favorite editor.

      The mappings contained in this file are used in several circumstances:
         loading songs from non-RISC OS hardware such as a PC formatted
          discs or PC/Unix/Mac OS networks.
         loading files from the Internet (browsers, FTP, ...).
         connection to Internet radio stations.

      It should be noted that old versions from filing systems like CDFS,
      DOSFS, Win95FS, LanManFS, LanMan98FS, Samba or even SparkFS don't use
      the MimeMap interface but use their own file type conversion systems
      (*DOSMAP, !CDFix, ...). Please refer to the manuals of these
      applications for more information.

      To ensure that DigitalCD and its associated modules perform all these
      actions correctly you should merge the mappings from this reference
      file in your MimeMap file.

      While doing so take the following points into account:
         Check not only that the mapping is already present but also
          correct. For example "audio/mpeg" and "audio/x-mpeg" mime content
          types are often incorrectly mapped to MPEG bf8 which is video MPEG.
         Also, on non-Select machines, the MimeMap process stop at the first
          match it encounters so pay attention to insert the mappings in the
          file before wildcarded mime content types such as "audio/*".
         Some versions of RISC OS may not support all the attributes in
          particular:
          1)   Mac filetypes (enclosed between "") may have to be removed.
          2)   Lines with "-" as mime content type denote mappings without
               corresponding mime content type. They may not be accepted in
               which case "-" should be replaced by a fake content type like
               "audio/x-pctk".

      Once the modifications are saved reboot or use the CLI command
      ReadMimeMap so that the system reads the updated file (this command
      unfortunately seems to perform its job correctly only under Select).
      Next, verify with MimeMap <mimetype> CLI commands that the
      modifications are taking effect correctly.

      If DigitalCD reports an erreur like "Unsupported file type (<filetype>,
      <mimetype>) or sub-format", it is probable that the mime content type
      displayed is not in your MimeMap file and the RISC OS filetype derived
      from a wildcarded mapping such as "audio/*". Should it be the case that
      the mime content type corresponds to a non listed mapping feel free to
      add the mapping to your MimeMap file and contact me so that I can add
      it to the mappings provided by DigitalCD.


                   Format of files with type FileList (type 155)
                   

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

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

      cur_path = ""
      prefix_dir = ""
      while more lines to read
      \
        read line
        line is in format <name> or <name>*<options>
        if name is dot terminated (name is a path)
        \
          if name starts with a dot
            cur_path = prefix_dir + name
          else
            cur_path = name
        }
        else if first line (the name defines a prefix)
        \
          prefix_dir = name
          cur_path = name + "."
        }
        else (name is a file/URL)
        \
          filename/URL = cur_path + name
          add (filename/URL, options) to list
        }
      }

      options has the following format:

      <name><value>,...,<name><value>

      where any "\" or "," character in a name or value is prefixed by a "\"
      to avoid confusion.

      the currently defined options are:
          f    flags (stored in decimal format)
               bits 0x001     this reference has already been played (files
                              or radios)
                    0x002     this reference could not be played (files or
                              radios)
                    0x004     this reference must not be played
                    0x008     this reference points to a playlist
                    0x010     this reference points to a directory (directory
                              list)
                    0x020     don't load the list pointed to on startup
                    0x040     this reference must never be played (files)
                    0x080     this reference was invalidated
                    0x100   this reference is an URL (radios)
                    0x200   
                    0x400   this reference is part of a compilation (files)
          a    name of the artist (files)/the radio station (radios)
          b    name of the album (files)
          c    comment
          d    number of the section to play (files)
          e    name of collective to which the artist belongs (files)
          g    name of the set to which the album belongs (files)
          m    mimetype (radios)
          o    order number in the album (files)
          p    points, stored in decimal format (files or radios)
          r    rate in kbps (radios)
          s    name of visual clue (files or radios)
          t    title (files)/name of the radio (radios)
          v    relative volume in % (files or radios)
          y    album release date in format YYYY or YYYY-MM or YYYY-MM-DD
          z    name of the metadata scanner to use (directory lists or
               playlists)

      File example:

      ADFS::HardDisc4.$.MultiMedia.Sound.Symphony.Songs
      .A.
      Anette*v250,f1
      ANewJack*tA new Jack,f1
      .B.
      Beams*tBeams of Light


                                Resources management
                                

      All resources not subject to change when DigitalCD is updated are
      stored separately from the main application. The directory used is
      called !DCDRes. When you install DigitalCD for the first time, extract
      !DCDRes from the archive, copy it to a suitable location then
      double-click on it to ensure that it takes precedence over the copy
      inside the archive.

      Initially, !DCDRes will only contain !Boot, !Help, !Run and !Sprites
      files. When you start DigitalCD for the first time, it will set up the
      following objects for you:

         A CDs file that will contain descriptions of your CDs that you will
          add by means of the CD database window.
         A Setup file describing which filetypes should be loaded by
          DigitalCD and which decoder(s) should attempt to play them. This
          file may be further edited to fit your own requirements, for
          example by configuring DigitalCD to automatically load itself and
          play certain filetypes when they are double-clicked.
         A Clues file contains small sprites for tagging playlist
          references. You can customise the Clues file by adding your own
          sprites or replacing those already present. Please contact me if
          you want to share the sprites you have created with other users.
         A Skins directory where DigitalCD stores its Default skin and where
          you should store any additional skins you download.
         A Plugins directory, split into Plugins.Desktop and
          Plugins.FullScreen. This is where the default visualisation
          plug-ins are stored, and where you should store any additional
          plug-ins you download.

      The CDs, Setup and Clues files are your own private copies of these
      files, and future updates of DigitalCD will never alter them. By
      contrast, default skins and plug-ins may be replaced by newer versions
      from time to time.


                                      License
                                      

      1.  Definitions

          The Software means the DigitalCD application and related files,
          i.e. the contents of the !DigitalCD and !DCDRes directories.

          The Developers means the developers of The Software or their
          nominated agents.

      2.  Warranty

          The Software is free (*) software. You use it at your own risk. It
          comes with no warranty at all.

          [* under the conditions outlined below.]

      3.  Copyright

          The Software is Copyright (C) the Developers, and is freely
          available under the terms laid out below.

      4.  Distribution

          Binary distributions will from time to time be released to the
          public by the Developers. These will be termed 'Official Binary
          Distributions' (OBDs).

          In addition the Developers may from time to time release customised
          versions to test groups. These will be termed 'Unofficial Binary
          Distributions' (UBDs) and may not be distributed outside the said
          test groups.

          No charge (other than media production costs) may be made for a
          binary distribution and the binary distribution must always be
          distributed unchanged.

          Permission is automatically granted to ship OBDs of the Software on
          any media (floppies, CDs, Internet site, computers, ...), as long
          as the said media doesn't contain any illegal, xenophobic or
          religious content.

          This means that anyone wishing to ship the Software (e.g. on a CD
          with a magazine, or with their own freeware or commercial
          software/hardware) in agreement with these conditions, only need to
          notify the Developers of his intentions as a matter of courtesy.

          Anyone wishing to ship the Software contrary to these conditions
          must contact the Developers for permission first.
                    
          Anyone flouting these distribution rules agrees to pay 1 million
          Euro (or a lower amount to be agreed with the Developers) to a
          charity nominated by the Developers.


                                      Credits
                                      

      Thanks to the authors of the following modules/applications:

      amp      AMPlayer             1.42    Thomas Olsson
      ds       DSymphonyPlayer      1.46    BASS 19911997, Freeware
      qtm      QTM Tracker          1.45    Steve Harrison
      trk      matrixTRK            0.89    Marko Lukat & Michael Pohle
      xpr      XprMod               1.10    Skoe of Expression
      tim      TimPlayer            1.27    Andr Timmermans
      smp      DiskSample           0.55    Andr Timmermans
               + AudioMPEG          0.33    Peter Teichmann
               + Ogg Vorbis         0.19    Andr Timmermans
               + AC3                0.06    Andr Timmermans
      playit   PlayIt               1.73    Rick Hudson & Christopher Martin
      mid      MIDIPlay             2.24    Expressive Software Projects,
                                             maintained by Liquid Silicon

          DCDUtils   0.35    Andr Timmermans
          AcornCD    0.19    John Beranek


                                      History
                                      

      Topic    Info
      
      Version 3.16  2023-12-21
      Player   Shift+Rewind/Fast forward works with files containing
               sections/chapters (or CUE files) played by DiskSample v0.59
               and above.
      Misc     Prefill yellow page's URL with "http://dir.xiph.org/yp.xml"
               since it is the only one I know of.
      
      Version 3.15  2022-09-17
      Misc     Fix for occasional failure to convert yellow page from UTF-8
               to Latin1.
          Ignore yellow page entries with <listen_url> element not starting
          with 'http://' to avoid https or empty element (why are such
          entries allowed?).
      
      Version 3.14  2021-09-11
      Bug Fixes:
      CDs Real fix for "Could not handle CD drive x" errors at startup.
      Choices  Iconbar choice "File queue" was opening "CD database".
      Player   "Stopping after 3 consecutive tracks fails to start" was not
               working for tracks opening in state "not ready" and falling in
               error after a delay (radios, some mp3s).
      Misc     Fix "List index out of bounds" error at startup.
      Misc     Fix for lack of menus and inability to quit after sending
               clipboard release message.
      
      Version 3.13  2020-04-02
      Bug Fixes:
      List     Loading a truncated xiph yellow pages list crashed because the
               incomplete track was deleted but not removed from the list.
          Improve yellow pages server name extraction, add genre into track
          "Info" field.
      Player   Changed behaviour when "Stop playing on error" is not set.
               When a track could not be played DigitalCD already tried 3
               consecutives tracks before stopping (a few failures is ok,
               more and it is probable that the whole playlist cannot be
               played). The problem is that for radios, the track "starts"
               safely while the connection is attempted and fails in the
               background. DigitalCD then just reported the error and stopped
               playing, now instead it will attempt to play the next track.
      CDs Delayed CD player list initialisation till the CD player panel is
          shown to avoid "Could not handle CD drive x" errors when starting
          DigitalCD with a CDDrive configured but no present.
      
      Version 3.12  2019-08-26
      Changes:
      Player   Restore old behaviour of playing next track when deleting
               current track.

      Bug Fixes:
      Player   Deleting the current track from a full screen plug-in (Delete
               key) crashes DigitalCD.
      List     One should not be able to insert tracks in a search results
               list.
          The presence of background jobs (like 'Validate') were stopping the
          distribution of Null events and preventing toolbars to be updated.
          Add the pane flag to generated toolbars to prevent the list from
          being constantly brought to top while dragging the toolbar.
          Copied/exported tracks were missing the original TimPlayer
          compatibility flags.
          Play from the list caused another track than the selected one to be
          played if DigitalCD neede to change the "program mode" to play it.
          Creation of new playlist, new dirlist and new failed since a few
          versions.
      CDs Forgot to pass on the configured DiskSample options when playing a
          CD (CD_ReadAudio mode).
          Player was reporting 'No CD present in drive' when it should report
          'Not an audio CD' when a non-audio CD is present in the drive.
      DCDLib   Window covering screen had auto redraw flag set which could
               lead to a brief flash of a white background before the plug-in
               redraws the screen.
      
      Version 3.11  2018-08-16
      Bug Fixes:
      List     Fix ordering of flat lists due to uninitialized variable.
      Misc     Fix zero pain during caused by search with scope "All
               playlists".
      DCDLib   Addition of PROCApp_SwapBanksNoVSync and PROCApp_WaitVSync to
               allow for non-visual processing between banks swap and VSync.
      CD  Was not setting DiskSample options (like buffer sizes) when
          starting to play in CD_ReadAudio mode.
      
      Version 3.10  2017-06-06
      Changes:
      Errors   When full screen plug-in is active, send error as message to
               be reported by the plug-in instead of using the usual error
               box.

      Bug Fixes:
      DCDLib   Update FNApp_String(ptr%,len%) to cope with NULL ptr%. Fixes
               zero pains in some plug-ins.
      Misc     Fix some zero pains.
      
      Version 3.09  2016-06-09
      Changes:
      CDs You can now delete CD descriptions from the CD Database.

      Bug Fixes:
      Tracks   Metadata extraction was not working properly in 3.08 due to an
               incorrectly fixed ZeroPain report.
      CDs Modifying the display options of a search results window caused the
          window's content to vanish.
      
      Version 3.08  2016-05-08
      Changes:
      List     Allow modification/saving of M3U/PLS files.
          Validate now works in the background.
          Added Alt+Click renaming of items.
          Increased loading speed of large lists like the xiph yellow pages.
      Search   Modified search for unplayed tracks to ignore tracks set never
               to play.
      CDs Rewrote CD Database in playlist form.
          Enabled and set default play mode to CD_ReadAudio as all new
          machines support it.
          Set default driver to SoundDMA for sampler target CD as
          CD_ReadAudio is routed through SoundDMA.
      Icon bar Load M3U/PLS list dropped on the icon bar.
      Misc     F1 in a window will open the corresponding StrongHelp file
               section.
          When user attempts to quit but cancels because of unsaved
          documents, open those unsaved documents.

      Bug Fixes:
      List     Flat and hierarchical view modes now lists files in exactly
               the same order.
          State of buttons and menus was not updated in some circumstances.
          Dropping a list on File Queue should add only file tracks.
          Dropping a list on search results window should not add tracks to
          it.
      Player   Current position in list could sometimes been lost when
               switching between Queue and Main playlist.
          Fixes some incorrect behaviour with moving to next/previous track
          like in short lists with unplayable tracks.
          Fixes some refresh problem and speedup switching of control panel
          to a new player.
          Fixes null pointer access while updating metadata information.
          Control panels other than primaty one where not removed anymore
          when 'single panel mode' option is activated.
      Tracks   Name filter crashed when you attempted to filter by a given
               letter after you just deleted the first name starting with
               that letter from the collection.
      Misc     Do not try to restore caret to save as box when aborting drag
               with Esc (Wimp closes the box before we receive the Esc).
      
      Version 3.07  18 Aug 2014
      Changes:
      Mixing   Mixing can now use the nearest 1x or 2x the track sample rate
               as replay frequency instead of the configured frequency.
      Tracks   Files     Unspecified track and section numbers are now shown
                         as empty instead of "0" to facilitate editing.
               Most TimPlayer options were moved from global Choices settings
               to individual track settings. TimPlayer compatibility flags,
               including the new Ultimate Soudntracker one, are now listed
               there too.
               Extend metadata extraction from filename with "#variable" a
               "." limited version of "%variable".
      Misc     Sliders now make now use of wheel mouse if OS support is
               present.
      Plug-Ins Updated DCDLib to use wheel mouse if OS support is present.
          Now provides to DCDUtils the playing module's name and handle so
          that plug-ins are sure to extract module specific info from the
          correct source.
      Choices  Players   Added option to pre-load the next track to play in
                         order to minimise gaps.
          Mixing    Updated with new frequency options.
               'Ignore system volume' option was moved here.
               Balance and Stereo separation are now in new subsection
               'Stereo'.
          CDFS Reorganised playing mode selection as a popup menu.
          DiskSample     Increased input buffer size limit to match the
                         latest version of the module.

      Bug Fixes:
      Choices  When reading saved settings, sample rates were clipped to the
               reasonable range available from the RPC, i.e [5000, 50000].
               Changed to [5000, 200000] to cope with modern hardware.
      
      Version 3.06  16 Apr 2012
      Changes:
      List     Show "<title> [<section>]" as track title if the track
               specifies a section. This allows to distinguish between tracks
               representing different sections of a same file.

      Bug Fixes:
      List     Tweaked scroll bar handling to take into account the column
               headers.
          Tweaked selection with the mouse to behave better under heavy load.
      
      Version 3.05  05 Mar 2012

      Changes:
      DCDLib   Allow full-screen plug-ins using this library to control the
               player with the mouse (Play/Pause, Rewind/Forward, Prev/Next
               section/track, Relative/Main volume Up/Down).
          Actions are mapped on the SELECT/ADJUST buttons, you just rotate on
          the available pairs of actions by clicking MENU.

      Bug Fixes:
      Player   Remote control of actions handled by a specific player was not
               working.
      
      Version 3.04  30 Dec 2011

      Bug Fixes:
      List     Fix occasional crash when double-clicking.
      CDs Fixes crash while exiting DigitalCD when CD is still playing.
      
      Version 3.03  27 Aug 2011

      Changes:
      Player   Shuffling options are now only shows by pressing MENU on the
               shuffle icon, while clicking SELECT will just toggle on/off
               shuffle.

      Bug Fixes:
      List     Double-clicks failed to work when the item was not selected
               beforehand. This is due to using Wimp_DragBox to start the
               (multiple) selection on the first click: the system doesn't
               see the need to report the double-click afterward.
          Ensure restored size of directory lists is not reset to default
          size while its content is still loading.
      
      Version 3.02  21 Aug 2011

      Changes:
      List     Include album's date in sorting options.
          If a group is selected, all elements within the group are
          considered as part of the selection.
      Player   Added turning shuffle on/off without having to change the
               shuffling options.
          Include album's date in sorting options.
      Tracks   Files:    New property to play all sections of the file
                         instead of a single section.
               New property to enter the album's release date (yyyy, yyyy-mm,
               yyyy-mm-dd).
               Extended metadata extraction from filename to extract album's
               date.

      Bug Fixes:
      List     Position of directory list windows were not saved.
          Playlists could not be moved within main playlist
          (non-hierarchical, unsorted mode).
      Player   Shuffle didn't work with File Queue.
          Don't reset "next track" position to 0 anymore when finishing to
          play the list. After adding extra files to the list, play will then
          restart directly from the new tracks when no shuffling is active.
      XprMod   This module sets the DMA size to 400, so it's best not to mess
               with it or the sound gets weird.
      
      Version 3.01  23 Jan 2010

      Changes:
      Choices  Added 'Ignore system volume' in Players section.

      Bug Fixes:
      Lists    Crash with Array out of bounds after sequence: drag multiple
               tracks from a secondary playlist to the file queue, set cursor
               in File queue to last track, unload secondary list (file queue
               is emptied), double-click on a file with 'Add to queue & Play'
               option active.
      Player   Playing not starting after sequence: empty file queue, drag
               multiple tracks from a secondary playlist to the file queue,
               click on play button.
      
      Version 3.00  03 Dec 2009

      Changes:
      Tracks   Use separate Properties windows for each kind of track.
          Files:    Properties for hierarchical info: Collective -> Artist ->
                    Box -> Album -> Title.
               New compilation (multi-author) album flag: Box -> Album ->
               Collective -> Artist -> Title.
               New track number field.
          Radios:   Properties for hierarchical info: Name -> Rate ->
                    Broadcaster -> MimeType.
          Directory lists/Secondary lists:
               New user configurable system to extract metadata from the
               file's name and path.

      Playlists     New 'File queue' list, a temporary playlist where to drag
                    files from the Filer or from other playlists, emptied on
                    exit of DigitalCD.
          New 'Yellow pages' lists to download lists of Internet Radios from
          the Net.
          A lot of grouping/sorting options.
          New 'Hierarchical' tree view mode.
          New 'Flat' mode with resizable columns.
          Some actions now take place in the background such as the scanning
          of directories or the download of yellow pages.
          New 'Create Internet Radio' dialog to define an Internet Radio
          withou the help of .m3u files.
          Search window:
               New 'All playlists' scope to search in all loaded playlists.
               New 'List' action to list the results in a 'Search results'
               playlist.
               Simplified text searching (filename or metadatas).
          Track shortcut. Used in search results and file queue lists to
          refer to a track in another playlist. Changes to the shortcut
          (edition, metadata provided by player), will in actually change the
          original track.
          The properties of multiple tracks can now be edited in one go.

      Player   New single panel mode.
          The Previous/Next buttons now start playing the previous/next track
          even when the player is stopped.
          Option to use 'Remove Track' command as simple marking of track as
          'Never Play'.
          Internet radios are now handled by a separate 'Internet Radios'
          player.
          'Music file' player:
               Old 'Program' versus 'Single track' system of 'Music file'
               player replaced by 'Program' versus 'File Queue' system.
               Old 'Program off & play' file loading options replaced by 'Add
               to queue' and 'Add to queue & play' options.
               Removed 'Reenable program on Stop' option.
               A lot of grouping/sorting options.

      Mixing   New option to choose DMA sound buffer size setting for
               compatibility with other applications.

      DCDLib   New functions to change screen modes, manage screen banks
               (RISC OS 6 compliant) and manage messages/title changes sent
               by the player.
          Documentation for the library added to !DigitalCD.DCDGuide manual.

      Plug-ins Documentation for DigitalCD_Misc message added to
               !DigitalCD.DCDGuide manual.
          New messages to ask full-screen plug-ins to display a message on
          the behalf of DigitalCD or change the song's title (well more a
          rotation of title, album, artist, ...).

      Drivers  Didn't catch DiskSample's clearing of metadata.
          Retrieve more metadata (track number, ...) from some drivers.

      Misc     Added smpext loader to pass the filename's extension to
               DiskSample in order to identify the type of a raw stream.
          Convert spaces to hardspaces in all filename icons.

      Bug Fixes:
      Lists    Do not validate URLs as files.
      Misc     Take into account (when possible) changes in system volume and
               ensure that plug-in volume scaling is correct.
      Drivers  Ensure PlayIt Config bit 2 is always off because it makes a
               mess otherwise and take system volume into account.
      Lists    Properties window did not allow filename to be changed to
               another playlist.
      
                                   Older history


                                      History
                                      

                                More recent history
      Topic    Info
      
      Version 2.56  28 Sep 2003

      Changes:
      Internet Added configuration of minimal buffering to do before start to
               play sound.

      Bug Fixes:
      CDs Internal API changes introduced a bug triggered by data CDs.
      
      Version 2.55  22 Sep 2003

      Changes:
      Drivers  Support HTTP streaming through DiskSample, with a redesign of
               APIs for metadata, position and status handling.
      Player   Rewrite display of metadata and timing.
      Playlists     Saving of URLs, loading of .m3u and .pls playlists.

      Bug Fixes:
      PlayList Fixed lists refresh when changing "Use file name as track
               title" option. 
      Drivers  Fixed Midi rewind/forward.
      PlayLists     Stop the currently played file before trying to remove it
                    from the list or before deleting the file.
      
      Version 2.54  21 Mar 2003

      Changes:
      Players  Timing now reflects the target position while dragging the
               position button.
          Added 2 new time modes: duration and total duration.
          Timing info is now refreshed in case of track duration updates.
      Playlists     Added Play button. Play while a sublist is selected will
                    play first allowed reference in sublist.
          Support of directory lists, directory based list which will be
          scanned when loaded to form a new temporary playlist.
          Lists can now have a base dir used as base for the names of files
          in the list. The list takes up less memory and makes it easier to
          manage when moving files around your disc.
          Load/Unload lists from memory at will.
          Filename field of unloaded lists can be edited in property window,
          a file may be dropped on the field.
          Validate now simply marks the problematic references with a
          question mark.
      Setup    New official filetype allocations for Ogg Vorbis,
               ImpulseTracker, FastTracker2, ScreamTracker3 and other PC
               trackers in default Setup file.
      Tracks   Filename field can be edited in property window, file can be
               dropped on the field.
      Choices  Players:  Added Reshuffle option to reshuffle once all tracks
                         have been played so that tracks of CDs or short
                         playlists are not always played in the same order.
          Drivers:  new AMPlayer section for the anti-shock buffer size.
      Plug-Ins Several desktop plug-ins can be activated at once.
      Drivers  Use AMPlayer intances.

      Bug Fixes:
      Players  Full size docking info was saved for mini-bar.
      Playlists     Search Window: fixed inversion of Playable/Not playable
                    scope.
          Fixed several errors in RAM transfer of lists (used by Dragging,
          copy/paste, etc).
      Plug-ins Don't autostart plug-ins for closed control panels.
      Drivers  PlayIt Config bit 2 when set does the inverse of what I
               expected in term of volume rescaling. 
          Incorrect reserved string size could freeze the machine.
      
      Version 2.53  26 Nov 2001

      Changes:
      Playlists     Search Window: added a few search scopes, control panel
                    list of files to play was never updated for some actions.
      Drivers  Included latest version of several modules.

      Bug Fixes:
      Misc     Fixed launch of DigitalCD by double-click on a file.
      
      Version 2.52  18 Jul 2001

      Bug Fixes:
      Playlists     Fixed loading of multiple sublists from the same
                    directory.
      
      Version 2.51  15 Jul 2001

      Bug Fixes:
      Playlists     Fix saving of main playlist when none exists.
      
      Version 2.50  07 Jul 2001

      Changes:
      Playlists     Extended search window.
          Playlists window is replaced by a Main Playlist. The control panel
          now lists all ticked files from every ticked playlist.
      Tracks   Support for track sections (subsongs).
      CDs Added option to start new CDs as soon as they are inserted in the
          drive.
          CD options are now on a drive by drive basis and there is a new
          option to use SWI CD_PlayTrack for drives who dislike SWI
          CD_PlayAudio.
      Icon bar Allow more windows to be opened from the icon bar (see Icon
               bar section in Choices window).

      Bug Fixes:
      Playlists     Fixed Copy/Paste in playlist from references with visual
                    clue icon.
      Drivers  A few bug fixes in the AMPlayer support.
          Some buggy CD drivers write 12 bytes of info for CD_GetAudioParams,
          causing a stack corruption within DigitalCD.
          Fixed volume 0 exception when converting from linear to log volume
          for PlayIt.
      
      Version 2.49  01 Nov 2000

      Changes:
      Playlists     The filelist window and menu redesign is complete. Lots
                    of extras: a toolbar, markers, a search window.
      Drivers  Allows overal volume * track amplification to exceed 100% for
               modules which support it.
          MP3 drivers will reject files with RIFF headers other than WAVE
          type 0x55 so that if you map filetype &FB1 to "smp,playit" or
          "amp,playit", MP3s stored as WAVE will be corrrectly played as MP3
          while the other waves will continue to be played by PlayIt. Beware
          that some other non-WAVE files may use this filetype and may then
          be played as MP3, so if you can, alter the filetype of MP3s stored
          as WAVE to &1AD instead of using this solution.
      Choices  DiskSample buffer sizes can be configured.
      
      Version 2.48  17 Sep 2000

      Changes:
      Players  Now displays temporary messages on certain actions.
      Drivers  Uses the latest versions of some modules (TimPlayer,
               AudioMPEG, etc).
      Skins    Skin selection menu now comes with submenus to reflect the
               skin directory tree. Skins may also provide a help file (!Help
               or !ReadMe).
      Plug-ins Oscillo plug-in now make use of the new FFT code in DCDUtils
               (click adjust on Oscillo window).
      Setup    In !DCDRes.Setup, adding '!' to the front of a filetype will
               cause DigitalCD to auto-play files of that type when they are
               double-clicked. DigitalCD must have been booted for this to
               work.

      Bug Fixes:
      Drivers  Fixed initialisation of 'Interpret unknown as' in PlayIt
               section of choices.
      Plug-ins Fixed the problem of plug-ins directories prefixed with "!".
               !Spectrum therefore doesn't need to be renamed to Spectrum
               anymore.
      
      Version 2.47  03 Apr 2000

      Changes:
      Playlists     Changes for updated clipboard protocol.
          Added 'External Source' playlist.
      Tracks   File properties now allows to edit the title/author of the
               track played. Changes to track title/author/scale volume don't
               mark the playlist as modified but the changes are
               automatically saved in the playlist file on exit of DigitalCD.

      Bug Fixes:
      Choices  Bug fix for 8-bit hardware users in Output->Mixing section:
               the frequency menu will now appear.
      
      Version 2.46  31 Jan 2000

      Changes:
      Samplers SoundDriver support code is working.
      Skins    Rebuilding the list of skins before displaying it becomes
               slow, so it will only be done from now on if you click on the
               popup icon with the right mouse button.

      Bug Fixes:
      Drivers  Correction for AmpDriver in loop on track mode, on track
               restart I didn't wait till AmpDriver is ready (track may
               remain paused).
      Choices  Choices window didn't provide access anymore to full screen
               plug-in info and setup icons.
      Samplers Default sampler drivers for File and Midi changed from None to
               SoundDMA.
      
      Version 2.45  24 Jan 2000

      Changes:
      Drivers  Support for AMPlayer.
      Skins    Skins may have subdirectories for different packs
      Choices  New sections layout for Choices window, for future extras.

      Bug Fixes:
      CDs Modified "WhichDisc" equivalent code to avoid calling the SWI
          CD_ReadData on audio only discs as it hangs the machine for CD
          drives connected to APDL's Blitz interface instead of returning an
          error.
          Slight bug in CD code (which track by track option off) which can
          prevent track one to be played.
          Moving preference list window while not on top of window stack
          could make one of the lists disappear.
      Misc     Problem with exception handling detected and caused by a
               return within a try block.
      
      ...

      Version 2.00  01 Dec 1996
          First release ready version.



    +----------------------------------------------------------------------+
    |                                                                      |
    | This text file was converted from a StrongHelp manual on 21 Dec 2023 |
    |                                                                      |
    |          using !StHlp2Txt version 1.12 (29 September 2009)           |
    |                           by Chris Morison                           |
    |                                                                      |
    |               email: organizer@morison.net                           |
    |                 web: http://www.organizer.morison.net/               |
    |                                                                      |
    +----------------------------------------------------------------------+
