stilview






stilview − command−line program to help you retrieve the
entries stored in STIL.

stilview [−b] [−d] [−e entry] [−f field] [−i] [−l HVSC base
dir] [−m]
             [−o] [−s] [−t tune number]

     stilview {[−h] | [−v]}

STILView is a command‐line driven program to help you
retrieve the entries stored in STIL fast and accurately.
STILView uses the STIL C++ class heavily to do this, and in
fact, the primary purpose of this command‐line program is to
test that class (which is, BTW, used in many GUI‐based SID
players, most notably in SIDPlay for Windows and XSIDPLAY
for Unix systems).  However, it is user‐friendly enough to
be used by non‐programmers, too.

Some terms and STIL‐related lingo in alphabetical order:

BUG ENTRY
    There exists a special file in HVSC
    (/DOCUMENTS/BUGlist.txt) that lists all known bugs in
    SID tunes in HVSC.  See the top of that file for details
    about what’s in it exactly.  A BUG entry is like a STIL
    entry, but it is contained in this BUGlist.txt file.

FIELD
    The smallest piece of information in a STIL entry.
    Currently valid field names are NAME, TITLE, ARTIST and
    COMMENT.

FILE‐GLOBAL COMMENT
    A special COMMENT field in a STIL entry for a multi‐tune
    SID file that refers to the whole SID, not just one tune
    in it. These usually contain general information about
    the SID file itself.

    Example:

      /Hubbard_Rob/Gerry_the_Germ.sid
      COMMENT: In Rob's own demo of this music, the tunes are named after the levels
               in the original game.
      (#1)
        TITLE: Lungs
      (#2)
        TITLE: Kidney
      (#7)
        TITLE: End

HVSC
    High Voltage SID Collection. If you don’t know what this
    is, you downloaded the wrong program. :)










                             ‐2‐


HVSC‐RELATIVE PATHNAME
    The pathname plus filename of a SID file that can be
    found in your HVSC, relative to the base directory of
    HVSC. It is always in UNIX‐style format, eg.:
    /Hubbard_Rob/Commando.sid refers to Rob Hubbard’s
    Commando.sid file within HVSC (which may actually be
    found as C:\Music\HVSC\Hubbard_Rob\Commando.sid on your
    Windows PC).

MULTI‐TUNE ENTRY
    A STIL entry that is referring to a SID file that has
    many tunes in it.  Each tune might have its own STIL
    block, which are separated by a so‐called tune
    designation in the form of "(#x)", where x = the tune
    number. Consult the STIL.FAQ in HVSC for a detailed
    description.

    Example:

      /Hubbard_Rob/Gerry_the_Germ.sid
      COMMENT: In Rob's own demo of this music, the tunes are named after the levels
               in the original game.
      (#1)
        TITLE: Lungs
      (#2)
        TITLE: Kidney
      (#7)
        TITLE: End

SECTION
    A part of STIL that belongs to one composer (ie. every
    STIL entry referring to SID files that are in one
    subdirectory in HVSC).  Sections in STIL are always
    separated by a line in the form of: "### Composer’s name
    ########".

SECTION‐GLOBAL COMMENT
    A special STIL entry that refers not to an individual
    SID file, but to a whole subdirectory. These usually
    contain info about the composer himself, or about all
    the SID file he/she ever composed, and are always
    indexed in the form of "/Subdir/" (note the trailing
    slash!).

    Example:

      /Hubbard_Rob/
      COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
               have often stolen Hubbard's routine causing some tunes to be falsely
               credited to him.
               Hubbard's own comments are denoted by (RH).

SINGLE‐TUNE ENTRY
    A STIL entry that has no tune designation in it in the









                             ‐3‐


    form of "(#x)", where x is a number. (Note, that a
    single‐tune entry might still refer to a SID file which
    has many tunes in it, ie. when a single‐tune entry has
    nothing but a COMMENT field in it!)

    Example:

      /Hubbard_Rob/Chain_Reaction.sid
      TITLE: Zoolook (remix) [from Zoolook]
      ARTIST: Jean Michel Jarre

    Another example (the SID this is refering to has many
    tunes in it!):

      /Barrett_Steve/Magic_Land_Dizzy.sid
      COMMENT: Also used in the game "Wacky Darts" (c) 1990 Codemasters.

STIL
    SID Tune Information List, essentially a text‐file
    database that can be found in your HVSC in the
    /DOCUMENTS/ subdirectory.

STIL ENTRY
    All of the pieces of information in STIL relating to one
    SID file of the HVSC. They are always indexed by the
    HVSC‐relative pathname.

TUNE
    One of the compositions in a SID. Most SID files have
    only one tune in them, but many have more than one (eg.
    one for the title score of the game, and one for the hi‐
    score music).



−b  Do not print BUG entries Default value: Not specified
    (ie. do print BUG entries)

    Example: "stilview −e=/Hubbard_Rob/Commando.sid −b"

    When this option is specified, BUG entries will not be
    printed for the given SID tune. At a minimum, the −e
    option has to be specified for this option to work.

−d  Default value: Not specified (ie. debug mode is off)

    Example: "stilview −e=/Hubbard_Rob/Commando.sid −d"

    Turns on debug mode in STILView. This will result in an
    extensive output, with the debugging messages going to
    STDERR. If you encounter any problem or strange behavior
    with STILView, run STILView with the exact same options
    as you did when you encountered the problem, with this
    −d option added to them. Capture the complete output of









                             ‐4‐


    this run, and send it to me with a detailed explanation
    of the problem (see email address at the top of this
    file).

−e=entry
    Default: NONE (you have to give an HVSC‐relative
    pathname to this option)

    Example #1: "stilview −e=/Hubbard_Rob/Commando.sid"

    Example #2: "stilview −e=/Hubbard_Rob/"

    This is where you specify the STIL entry you are looking
    for, given as an HVSC‐relative pathname. If there exists
    no STIL entry for the given filename, STILView will
    print out nothing. Otherwise, you’ll get the STIL entry
    (or parts of it, as you may have specified it by other
    options). HVSC‐relative pathnames are case‐insensitive,
    so /HUBBARD_ROB/Commando.sid is the same as
    /Hubbard_Rob/Commando.sid.

    Example #1 is the most frequent way of retrieving STIL
    entries, and it will return all of the STIL entry for
    Commando.sid, as well as the section‐global comment for
    /Hubbard_Rob/. Example #2 is another valid thing to do:
    this will return only the section‐global comment for
    /Hubbard_Rob/.

−h  Default: NONE Example: stilview −h

    Prints a brief help screen listing the available
    options. All other options that are also specified on
    the command‐line are ignored.

−f=field
    Default: all

    Valid values for <field> are: all, name, author, title,
    artist, comment

    Example #1: "stilview −l −e=/Hubbard_Rob/Delta.sid
    −f=comment"

    Example #2: "stilview −l −e=/Hubbard_Rob/Delta.sid −t=1
    −f=title"

    Example #3: "stilview −l −e=/Hubbard_Rob/Delta.sid −t=12
    −f=all −s −b"

    Asks for one particular field in a STIL entry. Combined
    with the −t option, these two options can retrieve any
    portion of a STIL entry, including a single field in a
    specific subtune’s entry. Below is full and complete
    explanation of what the different possible combinations









                             ‐5‐


    of the −t and −f options retrieve:

    "−t=0 −f=all" : All of the STIL entry is printed.

    "−t=0 −f=comment" : The file‐global comment is printed.
    For single‐tune entries that have nothing but a COMMENT
    field in them, this prints that COMMENT. For single‐tune
    entries that have other fields in them, this prints
    nothing. (This is because single‐tune entries with
    nothing but a COMMENT field are assumed to be file‐
    global comments.)

    "−t=0 −f=<name/author/title/artist>" : Nothing is
    printed. This combination of these options is invalid.

    "−t=<x> −f=all" : (Where x is anything but 0.) All
    fields from the portion of the STIL entry for the given
    tune number <x> are printed. For single‐tune entries,
    asking for −t=1 −f=all is equivalent to saying −t=0
    −f=all, since by definition, the whole entry refers to
    only one tune. (However, specifying −t with any other
    number than 1 will print nothing!) Note that if there’s
    a file‐global comment in the STIL entry (which also
    means that if a single‐tune entry has nothing but a
    COMMENT field in it), that is not printed with these
    combinations of options.

    "−t=<x> −f=<name/author/title/artist/comment>" : (Where
    x is anything but 0.) The specific field from the
    portion of the STIL entry for the given tune number is
    printed. For single‐tune entries that have nothing but a
    COMMENT in them, this returns nothing.

    Of course, if the STIL entry or any portion of it asked
    with these options does not exist, STILView will print
    nothing. Also, unless otherwise specified with the −o,
    −s and −b options, the section‐global comment and the
    BUG entry of the given SID file will also get printed
    (provided they exist).

    In example #1, the file‐global comment for
    /Hubbard_Rob/Delta.sid is printed, since −t is not
    specified and is assumed to be 0. Also printed are the
    section− global comment and the BUG entry for the same
    SID file (if they exist). In example #2, the TITLE field
    of the STIL entry for tune #1 of /Hubbard_Rob/Delta.sid
    is printed along with the section‐global comment and the
    BUG entry for the same SID file (if they exist). In
    example #3, all of the STIL entry for tune #12 of
    /Hubbard_Rob/Delta.sid is printed, but nothing else.

−i  Default: NONE

    Example: "stilview −i"









                             ‐6‐


    Starts STILView in interactive mode, ignoring all other
    options specified on the command‐line, except −l, −d and
    −m. In interactive mode, you can look for STIL entries
    by typing them in. You will get prompted for the desired
    STIL entry (which has to be specified with an HVSC‐
    relative pathname), for the tune number requested (which
    should be any non‐negative number, but this is not
    enforced), and finally for the specific STIL field you
    want to retrieve.

−l=HVSC base dir
    Default: The value of the HVSC_BASE environment variable

    Example #1: "stilview −l=C:\Music\HVSC\
    −e=/Hubbard_Rob/Commando.sid"

    Example #2: "stilview −l=../HVSC/
    =−e=/Hubbard_Rob/Commando.sid"

    Example #3: "stilview −l −e=/Hubbard_Rob/Commando.sid"

    This is where you tell STILView where it can find the
    HVSC base directory (the path to the directory has to be
    specified in the form required by your operating system,
    eg. C:\Music\HVSC under Windows, /home/lala/HVSC under
    UNIX). STILView will then try to locate the STIL.txt
    file in the /DOCUMENTS/ subdirectory of that directory.
    If this option is not specified (or if −l is specified
    without a base directory), STILView will try to extract
    the path of the HVSC base directory from the HVSC_BASE
    environment variable. If that environment variable
    doesn’t exist or is pointing to a location where there’s
    no STIL.txt file in a DOCUMENTS directory, STILView
    fails. If the HVSC_BASE environment variable exists and
    is valid, and this option is specified, the directory
    specified with this option is used as the HVSC base
    directory instead of the environment variable.

    In example #1 the HVSC base directory is located in
    C:\Music\HVSC\ on the hard drive of a Windows PC, in
    example #2 it is located in the HVSC directory of the
    current directory’s parent directory of a UNIX system.
    In example #3 the HVSC base directory is not specified
    with the option, so it is assumed that the HVSC_BASE
    environment variable contains the path to it. In
    reality, specifying the −l option in example #3 is
    redundant, and can be omitted.

−m  Demo mode

    Default: NONE

    Example #1: "stilview −m"










                             ‐7‐


    Example #2: "stilview −e=/Hubbard_Rob/Commando.sid −m
    −i"

    When specified, it prints out a whole bunch of things
    that a) test most of the functionality of STILView, and
    b) show what STILView is capable of retrieving from
    STIL. In example #1, the demo is printed with the STIL
    info coming from a default STIL entry, then STILView
    quits. In example #2, the demo is printed taking the
    STIL info from the specified STIL entry of
    /Hubbard_Rob/Commando.sid (instead of the default SID
    file), then interactive mode is entered.

−o  Do not print STIL entries

    Default value: Not specified (ie. do print STIL entries)

    Example #1: "stilview −e=/Hubbard_Rob/Delta.sid −o"

    Example #2: "stilview −e=/Hubbard_Rob/Delta.sid −o −s"

    When this option is specified, STIL entries will not be
    printed for the given SID tune (but section‐global
    entries and BUG entries will be printed, provided they
    exist and other options did not turn their output off).
    At a minimum, the −e option has to be specified for this
    option to work. Example #1 will print out the section‐
    global comment and the BUG entry for
    /Hubbard_Rob/Delta.sid, example #2 will print out just
    the section‐global comment for the same SID.

−s  Do not print section‐global comments

    Default value: Not specified (ie. do print section‐
    global entries)

    Example: "stilview −e=/Hubbard_Rob/Delta.sid −s"

    When this option is specified, section‐global entries
    will not be printed for the given SID tune. At a
    minimum, the −e option has to be specified for this
    option to work.

−t=tune number
    Default value: 0

    Example #1: "stilview −e=/Hubbard_Rob/Commando.sid −t=0"

    Example #2: "stilview −e=/Hubbard_Rob/Delta.sid −t=1
    −f=title −s −b"

    Example #3: "stilview −e=/Hubbard_Rob/Delta.sid −t=12"

    Asks for the portion of a STIL entry referring to one









                             ‐8‐


    particular tune. If tune number 0 is given, it retrieves
    all of the entry.  Combined with the −f option, these
    two options can retrieve any portion of a STIL entry,
    including a single field in a specific subtune’s entry.

    For further details about this option, see the
    explanation of the −f option.

    Example #1 retrieves all of the STIL entry for
    /Hubbard_Rob/Commando.sid, including the section‐global
    comment and the BUG entry (if any), but since the
    default value for this option is 0, it might as well be
    omitted in this example. Example #2 retrieves only the
    TITLE field of the first subtune’s entry for
    /Hubbard_Rob/Delta.sid (and not the section− global
    comment or the BUG entry), while example #3 retrieves
    all of the STIL entry for tune #12 of the same SID file
    (including the section‐global comment and the BUG entry,
    if any).

−v  Print version numbers

    Default value: Not specified (ie. do *not* print version
    numbers)

    Example #1: "stilview −v"

    Example #2: "stilview −e=/Hubbard_Rob/Commando.sid −v"

    When this option is specified, the version number of the
    STILView program and the version number of the STIL.txt
    file used by it is printed out. In example #1 this is
    the only piece of info that gets printed on the screen,
    in example #2 the version numbers are printed out, then
    the STIL entry for /Hubbard_Rob/Commando.sid is also
    printed out.



HVSC_BASE
    Specifies the location of the HVSC base directory.

All of the examples below assume that the HVSC_BASE
environment is set to a valid HVSC base directory (where the
$HVSC_BASE/DOCUMENTS/STIL.txt and
$HVSC_BASE/DOCUMENTS/BUGlist.txt files exist), and the
examples also assume the presence of the following entries
in these files:

      −−− In STIL.txt −−−

   /Hubbard_Rob/
   COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
            have often stolen Hubbard's routine causing some tunes to be falsely









                             ‐9‐


            credited to him.

   /Hubbard_Rob/Action_Biker.sid
   COMMENT: "Action B was a very early game and very conservative in it's approach
            − it was my idea of giving them what I thought they wanted, a simple
            cute tune....." (RH)

   /Hubbard_Rob/Commando.sid
   COMMENT: Tunes #1 and #3 have been converted from arcade version.

   /Hubbard_Rob/Delta.sid
   COMMENT: According to Hubbard, Kentilla and Delta were the most complicated one
            to compose, they took the longest time to do and they both drove him
            insane.
   (#1)
     TITLE: On the Run [from the Dark Side of the Moon]
    ARTIST: Pink Floyd
   COMMENT: It is more inspired by it than a remix of it.
   (#12)
     TITLE: Koyaanisqatsi [from the movie]
    ARTIST: Philip Glass
   COMMENT: "Inspired by Philip Glass and Pink Floyd." (RH)

   /Hubbard_Rob/International_Karate.sid
     TITLE: Merry Christmas, Mr. Lawrence [from the movie] (0:42−1:16)
    ARTIST: Ryuichi Sakamoto
   COMMENT: "[...] I started exploring pentatonic things in B flat minor over
            different bass notes, B flat, D flat, G flat and A flat. The middle
            section went into F (I think) at double tempo to liven things up. I
            was pleased with the tune......" (RH)

   /Hubbard_Rob/Rasputin.sid
   (#1)
     TITLE: Katjusha (0:07−0:36)
    ARTIST: Matvei Blanter, M. Isakovski
     TITLE: Katjusha (2:20)
    ARTIST: Matvei Blanter, M. Isakovski
     TITLE: Kaljinka (2:41−2:51)
    ARTIST: Traditional
   COMMENT: Russian folk song.
     TITLE: Kaljinka (3:12−3:22)
    ARTIST: Traditional
   COMMENT: Russian folk song.
   (#2)
   COMMENT: Russian folk song.

 −−− In BUGlist.txt −−−

   /Hubbard_Rob/Commando.sid
     BUG: This is just for demo.

   /Hubbard_Rob/Delta.sid
   (#12)
     BUG: Demo entry.









                            ‐10‐


     Given these entries, following are the printouts you
can expect from STILView. ($> denotes a command‐line prompt
given by your operating system.)

     Everything related to a SID file is printed:

        $> stilview −e=/Hubbard_Rob/Commando.sid
      −−−− GLOBAL  COMMENT −−−−
      COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
               have often stolen Hubbard's routine causing some tunes to be falsely
               credited to him.
      −−−−−− STIL  ENTRY −−−−−−
      COMMENT: Tunes #1 and #3 have been converted from arcade version.
      −−−−−−−−−− BUG −−−−−−−−−−
        BUG: This is just for demo.
   $>

     Ask for just the section‐global comment:

        $> stilview −e=/Hubbard_Rob/
      /Hubbard_Rob/
      COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
               have often stolen Hubbard's routine causing some tunes to be falsely
               credited to him.
   $>

     Note that this can also be retrieved with:

        $> stilview −e=/Hubbard_Rob/Commando.sid −o −b
      COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
               have often stolen Hubbard's routine causing some tunes to be falsely
               credited to him.
   $>

     This prints out nothing, as single‐tune entries do not
have file‐global comments:

        $> stilview −e=/Hubbard_Rob/International_Karate.sid −t=0 −f=comment −s −b
   $>

     ...Except if the only field in them is a COMMENT (in
which case that comment is assumed to be a file‐global
comment):

        $> stilview −e=/Hubbard_Rob/Action_Biker.sid −t=0 −f=comment −s −b
      COMMENT: "Action B was a very early game and very conservative in it's approach
               − it was my idea of giving them what I thought they wanted, a simple
               cute tune....." (RH)
   $>

     Also note that single‐tune entries have only one tune,
so asking for the STIL entry of tune #3 is pointless:











                            ‐11‐


        $> stilview −e=/Hubbard_Rob/International_Karate.sid −t=3 −s −b
   $>

     Print out the file‐global comment for the given SID
file:

        $> stilview −e=/Hubbard_Rob/Delta.sid −t=0 −f=comment −s −b
      COMMENT: According to Hubbard, Kentilla and Delta were the most complicated one
               to compose, they took the longest time to do and they both drove him
               insane.
   $>

     Print out the ARTIST field of tune #12 of the given SID
file, plus print out everything else related to the SID
file:

        $> stilview −e=/Hubbard_Rob/Delta.sid −t=12 −f=artist
      −−−− GLOBAL  COMMENT −−−−
      COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
               have often stolen Hubbard's routine causing some tunes to be falsely
               credited to him.
      −−−−−− STIL  ENTRY −−−−−−
       ARTIST: Philip Glass
      −−−−−−−−−− BUG −−−−−−−−−−
        BUG: Demo entry.
   $>

     Note that the current version of STILView is capable to
retrieve only the first specified field of a tune that
covers multiple songs! See below:

        $> stilview −e=/Hubbard_Rob/Rasputin.sid −t=1 −f=title −s
        TITLE: Katjusha (0:07−0:36)
   $>

     Section‐global comments are printed out even if the
STIL entry for the given SID file does not exist:

        $> stilview −e=/Hubbard_Rob/This_doesnt_exist.sid
      COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
               have often stolen Hubbard's routine causing some tunes to be falsely
               credited to him.
   $>

     The following 4 steps depict how to have STILView print
out everything related to a given SID file’s given tune
number one by one:

     1) This prints out just the section‐global comment:














                            ‐12‐


        $> stilview −e=/Hubbard_Rob/Delta.sid −o −b
      COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
               have often stolen Hubbard's routine causing some tunes to be falsely
               credited to him.
   $>

     2) This prints out just the file‐global comment:

        $> stilview −e=/Hubbard_Rob/Delta.sid −t=0 −f=comment −s −b
      COMMENT: According to Hubbard, Kentilla and Delta were the most complicated one
               to compose, they took the longest time to do and they both drove him
               insane.
   $>

     3) This prints out all of the STIL entry for the given
tune number:

        $> stilview −e=/Hubbard_Rob/Delta.sid −t=12 −f=all −s −b
        TITLE: Koyaanisqatsi [from the movie]
       ARTIST: Philip Glass
      COMMENT: "Inspired by Philip Glass and Pink Floyd." (RH)
   $>

     4) And this prints out just the BUG entry for the same
tune number:

        $> stilview −e=/Hubbard_Rob/Delta.sid −t=12 −s −o
        BUG: Demo entry.
   $>

     The following 3 steps depict how to have STILView print
out everything related to a given SID file:

     1) This prints out just the section‐global comment:

        $> stilview −e=/Hubbard_Rob/Delta.sid −o −b
      COMMENT: All of these tunes have been confirmed by Hubbard to be his. People
               have often stolen Hubbard's routine causing some tunes to be falsely
               credited to him.
   $>

     2) This prints out all of the STIL entry:

        $> stilview −e=/Hubbard_Rob/Delta.sid −s −b
      COMMENT: "[...] The Delta music loader and ingame music was Gary Liddon's idea.
               [...] He was the producer at Thalamus at the time. He told Rob Hubbard
               to make the ingame music like the 2nd track from Dark Side of the Moon
               by Pink Floyd." (Info from Matt Furniss.)
               "The small jingles are all small clips from Sanxion and Romeo/Juliet
               music. They were all supposed to be for short stingers such as end of
               level, extra life etc..."
               "Delta was based on this minimalist composition technique inspired by
               Glass and a bit of Pink Floyd. It was quite hard too do and required
               some custom code to the driver to do it. The music was tedious to









                            ‐13‐


               debug. The other Delta stuff was more conventional − I quite liked the
               other tunes. Delta was spread over a 2 week period....." (RH)
               According to Hubbard, Kentilla and Delta were the most complicated one
               to compose, they took the longest time to do and they both drove him
               insane.
      (#1)
        TITLE: On the Run [from the Dark Side of the Moon]
        ARTIST: Pink Floyd
      COMMENT: It is more inspired by it than a remix of it.
      (#12)
        TITLE: Koyaanisqatsi [from the movie]
       ARTIST: Philip Glass
      COMMENT: "Inspired by Philip Glass and Pink Floyd." (RH)
   $>

     3) And this prints out all of the BUG entry:

        $> stilview −e=/Hubbard_Rob/Delta.sid −s −o
      (#12)
        BUG: Demo entry.
   $>



LaLa <LaLa@C64.org>
    Original author.

Leandro Nini <drfiemost@users.sourceforge.net>
    Current maintainer.



SourceForge project:
    <http://sourceforge.net/projects/sidplay−residfp/>

High Voltage Sid Collection (HVSC): <http://hvsc.c64.org/>



Copyright (C) 1998, 2002 LaLa

Copyright (C) 2012−2016 Leandro Nini

     This program is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.

     This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.  See the GNU General Public License for more
details.









                            ‐14‐


     You should have received a copy of the GNU General
Public License along with this program; if not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth
Floor, Boston, MA  02110−1301, USA.