



     PlayMATE v.4 - A music composer for PC Speaker written in QuickBASIC




TRACKER

  > Tempo And Time Signature
    The time signature and tempo is located belowed the menu bar, to the left.
    Click that area to open a window where you can set the tempo in beats per
    minute (a value between 32 and 255 included) and the time signature via
    the two controllers next to the "signature" label. The numerator shows the
    number of beats per bar (a value between 1 and 16 included) and the
    denominator represents the length of a beat (2 is half a note, 4 is a
    quarter, etc.) The time signature provides a visual aid and doesn't affect
    the way the music is played.

  > Horizontal Scroll Bar
    Modifies the currently displayed bars.

  > Vertical Scroll Bar
    Modifies the currently displayed octaves.

  > Tracker area
    Left click on an empty space to start drawing a note; notes are
    represented as lines with two handles. Left click and drag any handle to
    modify the note duration. Click anywhere else on the note, then hold and
    drag to move the note left or right. When you click above or below an
    existing note, it will be displaced to the cursor's vertical position. Due
    to the way PC Speaker work, notes cannot overlap; the program will clip
    notes if necessary before saving or playing. Right click above, below or
    on a note to remove it.

  > Status bar
    The status bar displays multiple things. On the left, it shows the note
    currently hovered (N followed by the note number, then the tone, the
    position, and the length.) Then appears an approximation of the playing
    time of the whole track and the current playback status (PLAYING, STOPPED
    or WAIT followed by the number of PLAY instructions left in the queue.)
    Finally, all the way to the right is the number of notes used and the
    total number of notes available.


MENUS

  File

  > New Tune
    Unsaved changes made to the current track will be lost.

  > Open Tune
    Load an SPK file; unsaved changes made to the current track will be lost.

  > Save
  > Save As
    Save the current track to an SPK file.

  > Quit
    Quit to DOS. Unsaved changes made to the current track will be lost.


  Tools

  > Transpose
    Modify the pitch of a section of the tune. Select the range to modify by
    adjusting the "from bar "and "to bar" (by default the first and last bars
    containing notes in the current project,) then specify the pitch in
    octaves and semi-tones (1 octave = 12 semi-tones.) If the "clip notes" box
    is checked, all notes falling outside the valid octave range (below 0 or
    above 6) are removed from the track.

  > Copy Bars
    Copy a defined amount of bars from "source bar" to "target bar." If the
    "insert" box is checked, those bars are added to the track, rather than
    replacing existing notes.

  > Insert Bars

  > Remove Bars


  Playback

  > Play Once
    Play the track starting at the first note visible in the tracker. You can
    also press the space bar anytime to play or stop the playback.

  > Play Loop
    Plays the whole track, from start to finish in a loop.

  > Stop
    Stops refilling the playback buffer.


  Settings

  > Visuals
    Configure interface colors and appearence. You can either pick one of the
    predefined theme or choose your own colors.

  > About
    Version number and credits.


SAMPLE TRACKS

  BANNER.SPK   - "The Star Spangled Banner"
                 John Stafford Smith / Francis Scott Key
  CANCAN.SPK   - "Infernal Galop"
                 Jacques Offenbach
  ELISE.SPK    - "Fur Elise" (clip)
                 Beethoven
  MOONLGHT.SPK - "Moonlight Sonata" (Piano Sonata n°14 - clip)
                 Beethoven
  OP69_1.SPK   - "Farewell" (Opus 69, n°1)
                 Frederic Chopin)
  OP69_2.SPK   - "Waltz" (Opus 69, n°2 - clip)
                 Frederic Chopin
  SKATERS.SPK  - "Skater's Waltz" (clip)
                 Emile Waldteufel
  JINGLE.PSK   - "Jingle Bells"
                 James Lord Pierpont
  MERRY.SPK    - "We Wish You A Merry Christmas"
  SANTA.SPK    - "Santa Claus Is Coming To Town"
                 J. Red Coots / Haven Gillespie
  SILENT.SPK   - "Silent Night"
                 Franz Xaver Gruber / Joseph Mohr


EXPORT/IMPORT PLAY

  The new file format is little more than a PLAY command string with a header.
  The first line has to be "'PlayMATE" and any line starting with "'" is read
  as meta data or discarded. Lines that do not start with "'" are stitched
  together and decoded like a PLAY command string.

  When saving tracks, PlayMATE will insert space every 6 notes to ensure the
  buffer can be played in the background. Stuff the whole string (including
  the terminating space) in a string variable (plTune$ in the following code,)
  and add the following code to play each chunk of the track one after the
  other, in the background:

    DO
      IF PLAY(0) < 3 THEN
        plPos2% = INSTR(plPos1% + 1, plTune$, " ")
        PLAY MID$(plTune$, plPos1% + 1, plPos2% - plPos1%)
        plPos1% = plPos2%
      END IF
    LOOP UNTIL (plPos1% = LEN(plTune$)) OR LEN(INKEY$)

  It is also very easy to make it loop by simply adding the following line
  right after "plPos1% = plPos2%":

    IF plPos1% = LEN(plTune$) THEN plPos1% = 0


HOW TO RUN PLAYMATE IN THE QUICKBASIC 4.5 IDE

  First, you need to compile the WINLIB library. Run QuickBASIC 4.5 with the
  /L switch, open WINLIB.BAS and then RUN > Make Library. When the library is
  compiled, exit and run QuickBASIC 4.5 again with the /L switch followed by
  WINLIB. Open PLAYMATE.BAS and you're good to go. At that point, you may
  recompile the application as a stand alone executable.


NOTES

  This program has been tested in DOSBox only so there's no guarantee it will
  run on the genuine hardware; if it does, something akin to a 80386 @33Mhz
  should be able to run it without issue.


VERSION CHANGES

  .1 November 20th, 2020
    - Initial release

  .2 November 24th, 2020
    - Fixed a timing issue where notes and pauses would last longer than they
      should.
    - Increased maximum note duration from 32 to 64 beats (2 bars in 4/4.)
    - The PLAY command string generation has been optimized for space: when
      possible, the "Ln" command is used to shrink consecutive notes of the
      same length. The "On" command is replaced by ">" and "<" for neighbor
      octaves. Pauses are replaced by "N0" if their length matches the current
      "Ln". These tweaks shrink PLAY command strings by 30% on average.
    - The "Copy Bars" window has been slightly modified: the field "number of
      bars" has been replaced by the last bar to copy.
    - Tracker drawing routine optimized; the freed cycles are used to display
      the currently hovered beat and note on the vertical and horizontal bars
      of the tracker.
    - Fixed two possible crashes caused by very large measures (when using
      time signature 16/2 for instance.)
    - Fixed a crash when trying to play very large files; the playback buffer
      can no longer overflow but is 4096 bytes long. It may be sufficient for
      most uses (might need to rewrite the playback and export system.)
    - Some fixes in the import function; it's still not the most robust thing
      out there though.
    - File format has been modified (takes more space, quicker to process.)
    - Escape can be used to close dialog boxes (unless an input field has
      focus.) Space will play/stop music playback.

  .3 November 28th, 2020
    - This version drops the binary file format in favor of a plain text file
      containing PLAY instructions. The first line has to be "'PlayMATE" and
      it may include a time signature in the form of "'TimeSignature 4 4".
      This choice was made because the compression code for PLAY strings
      provides shorter files, it allows more flexibility for meta data, and
      it's easier to import (and export) music from (and to) QB programs.
    - The order of note() is maintained when notes are added or removed, so
      there's no more need to sort the array before playing/saving projects,
      it also allows a much faster search system to retrieve note indices
      according to their offset.
    - Tracker drawing routine optimized again.
    - Fixed a few visual glitches.
    - Fixed a bug where copied bars would not be inserted.
    - Added more info to the status bar: total playing time, playback status,
      the number of notes used in the track, and the playback buffer
      saturation. The playback status displays "PLAYING" when playback is
      enabled, "STOPPED" when the playback is off, and "WAIT" followed by the
      number of PLAY commands left to process when the playback is about to
      end.
    - Note resizing/moving prevents overlap.
    - Modified the time signature/tempo window: click "Preserve Time" to
      rescale the length of every note so the song plays the same after
      modifying the tempo. This option replaces "Scale Tempo."
    - Added two new tools: insert and remove bars.
    - Playback buffer size increased to 8192 bytes.

  .4 December 22nd, 2020
    - Playback buffer saturation displayed in bytes rather than percent.
    - Fixed actions not changing the project status (no "file changed" prompt)
    - Fixed a PLAY rule for import: when N is used to specify a tone, the
      default octave is set to the octave above that tone.
    - Fixed status bar incorrectly displaying a selected note on startup.
    - Added directories to file load/save window (required some tweaks in
      WINLIB to avoid running out of memory by removing useless list data.)
    - Fixed a crash caused by loading an empty (no PLAY commands) file.
    - Fixed a crash caused by saving an empty project.
    - I think the crash on exit is gone for good; might have been related to
      guiInit although I'm not sure what happened. Too random to be sure.
    - Tweaked WINLIB so controllers are 32 bytes long instead of 64.


- Mike Hawk

https://qbmikehawk.neocities.org/