0. About this readme

This text contains information about the modified version of the
SBaGen program, which is created and distributed by Jim Peters
under the terms of GNU-GPL license version 2. This modified version
is based on SBaGen V1.4.3 and includes four application versions,
three of which are meant to be used under the desktop MS Windows
(NT V4.0 - NT V6.0 ("Vista"), and also Windows 98/ME). The fourth
version is for Windows CE V4.0 (Pocket PC 2003) and Windows
Mbile 2005. All versions are named SBaGen V1.4.4R, and are
subject to the same GNU GPL V2 (see the COPYING.TXT file).

To use the above applications efficiently, you should be familiar with
original user manual SBAGEN.TXT, which can be found inside all the
SBaGen V1.4.3 packages (see http://uazu.net/SBaGen/). You will
also find inside a large collection of sample scripts, fully compatible
with all versions provided.

The following description assumes the understanding of all warnings,
operation basics, command shell and script language of the original
SBaGen.

1. Why V1.4.4R?
---------------
My first touch to SBaGen made an impression that the idea is hugely
interesting and useful, but the implementation is not very user-
friendly. Not the command shell interface was the reason; it was a PC
desktop (big, noisy, overheating) that never inclines you to a peaceful
meditation over our beautiful software. I was pleased to discover a
Windows CE version. Downloading and testing (at the friend's PPC)
showed that this version works. Promptly after that I purchased a
PPC with Windows Mobile 2005. The result was disappointing. Close
look indicated a strange behavior of the application (SBaGence). It
doesn't support many features of desktop SBaGen. It also sometimes
disappears after one or two hours of execution.

I was generally dissatisfied with SBaGence, but the money I spent for
PPC, and the desire to get a version of SBaGen which answer me,
didn't allow me throwing the PPC away.

After the analyzing of the SBaGence's internals I concluded, that
putting the code of the command line utility into separate thread, and
redirecting of the output from the console to graphical window is a
great idea, but the implementation looks as a "one evening work". So,
SBaGence was disposed of, and the work started from ground up.
The task was not found to be trivial, so I coded the application
through step-by-step iterations.

First, SBaGenr came - a command shell application similar to the
original SBaGen, but prepared to be used as "thread" (particularly, it
released the used resources at the end of its execution).

Further, SBaGenw was released - Win32 GUI ASCII/ANSI program
prototype compiled from the same sources as SBaGenr. It had a
much simplified interface which, however, preserved all the features
of the original program.

Next, SBaGenwu came - Win32 GUI application, which used
UNICODE system calls (it doesn't work under Windows 9.x/ME).

And, SBaGene - the final application for Windows CE.

During the development, some bugs were fixed. I achieved the
compatibility with Windows Vista. Also, now it is possible to select
arbitrary times into the embedded session -p drop.

After I released the beta version, several pretty serious bugs
unveiled. I removed everything found enough serious (see the Known
Bugs for the rest). Following the multiple requests from the beta
testers, I restored the support for the OGG format for the background
sounds (including the looped OGG), and for the MP3. Moreover, I
slightly updated the GUI for the Win32 versions (SBaGenw) with the
sizable main window. You'll also find additional command line
options, and the "mute tool" allowing muting of the separate channels
in quazi-real time (in GUI Win32/CE versions only).

2. Description of the applications
----------------------------------
2.1. What's changed in shell commands (SBaGenr, -w, -wu, -e)
------------------------------------------------------------
Parameters -M (input of sound from the standard input stream) and
-O (output of sound to the standard output stream) are excluded from
graphical versions. Though these keys are present in the command
shell version, they will certainly not work correctly under Windows.
Stdin and stdout are the text files there, and C runtime library
performs some additional processing while handling them.

For the -m parameter (setting of mix sound file), a new -m+ version
was added. This key allows looping a WAV/RAW fragment. For
example: -m river1.wav is used to achieve one-time replay of a mix
sound, after finishing playing of current sequence the termination
message "End of mix input audio stream" will appear. Using the form:
-m+ river1.wav, you will get an unlimited background source.

Note that m+ will not work for the OGG/MP3 files; you will get a
notice when using this type of files.

For all the Windows versions, the following key was added:
-B <buffer-size>,<buffer-count>
This allows setting of the optimal size and buffer number for the
sound card output. The key will truncate these parameters down to
the nearest power of 2. The default is -B 32768,8; minimum is
-B 1024,2. Generally, the default values are a little bit high for an
average system. You'll achieve good results setting B 8192,4 or
B 8192,8. A good sense in changing the buffer size (lowering it in
most cases) occurs when your systems encounters clicks and other
artifacts not tied with amplitude overhead.

For all the Windows versions, the following key was added:
-l <n-looper>
n-looper is not-negative decimal number. It has the same meaning as
in the m ogg-file.ogg#<digits> phrase. This is useful when a looped-
ogg file is selected with the standard Windows dialog. For scripting
convenience, when the looped-ogg files are set, you may use "!"
synonymic to "#", e.g. the following is the same:

-m ogg-file#1
-m ogg-file!1
-m ogg-file l 1

For the -p drop sequence, an "awake" '!' synonym was added for the
symbol '^'. For example, the following notations are equivalent:

-p drop "00ds+^"

and

-p drop 00ds+!

Notice quotation marks in the first notation. They are needed in
Windows CMD command shell, because symbol '^' is a meta-symbol
of the Windows shell (CMD).

Other options are left unchanged.

2.2 Working with graphical versions (SBaGenw, -wu, -e).
-------------------------------------------------------
The graphical interfaces of all GUI versions of the program are
identical. Application has a main window with caption, that displays
the program status (There are two stopped conditions: Stopped and
Stopped/Error. The later indicates that the working thread of SBaGen
has terminated due to error condition and with error message, which
you can read).

There are six buttons at the top of the window.

>> - execute a session / script according to the parameters set
(clicking the button with no parameters selected is similar to starting
command shell version without any command line parameters - a
short help message is displayed, and the application returns to its
initial state).

||| - stop playback of the current session. The application returns to its
initial state. A delay of up to 1 sec may occur after pressing this
button, needed for perfect shutting down of all the working threads.

... - displays standard "open file" dialog for selecting a playback
script. Default extension is .sbg, though selection of txt file is also
possible, which could be useful on PPC, since MS Pocket Word can't
open files with arbitrary extensions.

X - cancel selection of a script. This button is meant to be used with
pure command line w/o any script. It is unnecessary to use this
button when selecting a new script.

++ - displays a dialog for selection of additional options (see
description below).

Exit - terminates the program regardless of its current status.

Below the buttons there is a text field, showing current parameters
(script file name, command string and the name of "mix" file) in the
process of their modification by the user (in the stopped state) along
with all console output of SBaGen (in the running state). Virtual
screen size is 512 rows with 512 symbols in each row.

Pressing "++" button opens "Command Line Head" dialog box to set
the additional command line options.

Upper input field provides parameters similar to those in SBaGen
command line. All parameters are space separated. When entering a
parameter that includes a space character, enclose your parameter
into quotes, for instance:
-oW "\SD Card\out\play.wav"
sets directing the generated audio to the file \SD Card\out\play.wav.
The quotes are the must, as "SD Card" includes space.

As another example, entering
-h
in the command line, and pressing the ">>" will show the help
information on the application switches.

Two buttons for selecting a background sound (WAV/RAW) or
canceling the selection, are located at the left lower corner. After a
file is selected, the command line automatically extends with a -m, or
-m+ switch (depending on the "Repeat" checkbox to the right of the
"Mix..." button).

"OK" and "Cancel" buttons are traditional.

The command line, which send to SBaGen code, formed as:

1st parameter: application name

If a mix file is defined (selected), 2d and 3d parameters are "-m" (or
"-m+"), and a full filename, appropriately.

Next, the additional parameters string follows (if any).

The script filename (if any) placed as last parameter in the command
line.

The command line is processed by the "native" SBaGen code after
the ">>" button is pressed, with no graphic environment involved. On
errors, diagnostic messages appear, otherwise the command
executes just like it was entered in the command line of the SBaGen
application.

2.2.1. Mute tool
----------------
The current GUI versions for Win32/CE includes additional feature to
control the playback of separate channels in real time (accurate
within the sound buffer size). During the playback, the "options" ("++")
button (yet disabled) turns to "Mute Tool" button; this button activates
(for playback only) the channels control panel. This panel includes
16 channel disable buttons (pressed state means a channel is disabled),
and traditional OK and Cancel ('X') buttons that clear up the Mute
Tool panel with or without saving the channel muted status.

The Mute Tool is mainly used to debug the complicated sessions
(over 3-4 channels). Particularly, it can help in the case of distorted
sound that frequently appears when applying a non-properly
arranged script to a non-perfectly prepared background sound.

Note that: (1) the muted status for channels is preserved for the
application lifetime, and can be changed only via the Mute Tool
panel; (2) the Mute Tool panel is available during the playback only;
(3) when the playback is over, the Mute Tool panel will shut down
automatically with OK action (i.e. saving the status).

2.2.2. Notes
------------
Note 1: The Win32 versions treat the immediate command line like
the original SBaGen application, i.e. in the form of parameters listed
after the executable filename. The distinction is that this command
line is executed only by pressing the ">>" button. This allows setting
the frequently used parameters to the properties of the application
link.

Note 2: SBaGene at PPC supports both portrait and landscape
screen modes statically: the current mode is fixed after the
application started.

Note 3: All the graphical SBaGen versions allow launching only one
copy of the application; attempt to start a second copy will only set
the focus to the running application window.

3. Contents included
--------------------
SBaGenr comes as ZIP archive that includes full tree of code files,
appropriate win32 project files (arranged into single MS Visual Studio
6.0 workspace), and Windows CE project files (separate MS Visual
Studio Embedded 4.0 workspace), pre-compiled executables in the
following folders:

SBaGenr\release\SBaGenr.exe - Win32, command line;

SBaGenr\SBaGenw\release\SBaGenw.exe - Win32 GUI, ASCII;

SBaGenr\SBaGenw\SBaGenwu___Win32_Release\SBaGenwu.exe 
   - Win32 GUI, UNICODE;

SBaGenr\SBaGene\xxxRel\SBaGene.exe - Windows CE; were xxx is 
the processor type (FOR THE MOST PPCs 
SBaGenr\SBaGene\ARMV4Rel\SBaGene.exe);

All versions require no installation, they don't use the Windows
registry, and need no uninstall procedures.

To install, you only need to extract the applicable executable file to
any folder and, if needed, to create a link to this file.

The sample scripts must be additionally extracted from the original
SBaGen project (to be downloaded) (I recommend downloading the
archive, not the setup application), together with the text
documentation.

4. Known Bugs
-------------
1. (CE only) when launched on the empty desktop ("Today" screen)
by the link from the "Recent applications" the virtual keyboard is
unavailable; this makes it impossible to enter additional command
line parameters. The problem is absent when the application starts
with any other application already launched, or from the explorer, or
via the Start -> Programs menu. The solution would involve
generating separate versions for PPC, smartphones, and "Generic
CE". I guess this is a misery inconvenience.

2. (CE only) redirection to a file problem. The CE supports output to
RAW (-o) or WAV (-oW) (I wonder the purpose). BUT, by experience,
this works extremely slowly, and from the start to the end of process,
it's better to avoid any intervention to machine. Obviously, this is not
a SBaGene bug, as Windows Explorer shows the same performance
when copying large files (over 20MB) from CF to SF (for instance) -
up to the complete hanging up. By anyway, please note, that on CE
you MUST to enter the full output file name.

3. (CE only) as Windows CE doesn't support current folder for a
process, all the filenames must be supplied with full path, starting
from the root. Using the file selection or script selection dialog
resolves the problem automatically; the manual entering of the file
names remains inconvenient.

4. (All GUI versions) there is no quotes pair check for the command
line parameters; a missing quote will interpret all the text till the end
of line as invalid "long" parameter.

5. (All versions, including the original) for sound layers, only
WAV/RAW, PCM/16 bit, stereo audio files are acceptable. Moreover,
a file must be over 1MB long (approx.). Unfortunately, for now any
WAV/RAW file is treated as the above format (the application cares
only of the sampling frequency); this sometimes may give the
unexpected results. I currently didn't decide what to do with other file
formats (like 8-bit or mono): to wake an error "not supported"
message, or to try to play them correctly. (This problem is also
present in the original SBaGen.)
The OGG files must include 2 channels (no other limitations); for MP3
files single channel (mono) is acceptable.

6. (All versions, including the original) "tails" of non-looped
WAV/RAW and OGG as well as all MP3 background mix sound in
general are truncated. The lost fragment length may be up to 1 sec. I
could not find a graceful satisfactory cross-platform solution within
this release. As a general workaround, you can add an additional 2-
seconds empty tail to the files that will not be looped.

7. (All versions, including the original) when playing back the
background MP3 files, messages like "MAD recoverable error: ........"
may appear. This generally doesn't indicate any format damage
and/or a playback error.

7. (All versions, including the original) for some command line
options, the program acts depending on the parameters order, in
general, the '-i' and '-p' options must be placed at the end of the
command line  this is not a bug.

5. Changes in version 1.4.4R over the original 1.4.3
----------------------------------------------------
-- splitted the sources and reformatted the code; thread start/stop
   for Windows fixed;
-- free all the resources at exit (exit(int)) replaced;
   -p drop '!' as synonim for '^' added. Synch with read thread for
   windows,
-- added -m+ for endless repeating of wav/raw mix,
   added support for compilation as win32 GUI application
   (ASCII/ANSI and UNICODE) (all the stdio screen output
   functions replaced),
-- added support for compilation as Win CE (PPC 2003 and
   Windows Mobile 2005) w/o any additional libs,
-- fixed code for Windows Vista Support
-- fixed -p drop with non-standard timing
-- *NEW* fixed program crush at empty scripts
-- *NEW* for select parameters section for looped OGG files l n 
   switch added, as well as symbol '!' can be used as synonim for
   '#' in context "-m file.ogg#n"
-- *NEW* for fine tuning to any sound card for Windows versions,
   B bSize,nBuf parameter added.
-- fixed working with *.wav files (but the wav's different from 16
   bit/stereo/PCM stay handled incorrectly).
-- *NEW* fixed some GUI bugs of beta version (system resources
   and memory leakage, possible message dropouts)
-- *NEW* Win32 main window is now sizable (maximizing is not
   supported yet)
-- *NEW* Mute Tool
-- *NEW* Source Linux compatibility
-- some minor changes.

-- Now there are 4 projects for Windows:

-- SBaGenr.exe -- plain command line utility;
-- SBaGenw.exe -- WIN32 GUI ASCII/ANSI appl;
-- SBaGenwu.exe -- same, but using only UNICODE system calls;
-- SBaGene.exe -- PPC versions for many different CPU

NOTE: SBaGenw and SBaGenwu were never planned to be
separate programs; I wrote them as approaches for the PPC
SBaGene, but, probably, they may be found useful for somebody.

NOTE: all the projects compile from the same code tree.

NOTE: if somebody will attempt to add for PPC SBaGene "shell
extensions" (i.e. association SBaGene.exe with *.SBG-files), this
probably will work incorrectly  as I don't plan this feature, I don't
precisely know how to make it working under CE.

Notes on PPC application performance
------------------------------------
As PPC resources are limited, I must forewarn on some problems. If
we took a CPU like ARMV4(i) 200 MHz as a basis:

1) no problems will arise for the most complicated sessions (up to
16 channels), with background sound in WAV/RAW format.

2) when using a background MP3 or flat (non-looped) OGG file, in
most cases everything will work properly assuming the SBaGen is a
single application that consumes CPU resources, and the user have
no attempts to interactively work with the machine. Unfortunately, the
tests showed that a 200MHz CPU operation depends on the file
encoding method (especially for MP3), i.e. workability is not
guaranteed. Apparently, more powerful CPUs will avoid problems
with MP3/non-looped OGG files.

3) playing back of looped OGG files at 200MHz CPU is impossible.
This problem surely dissipates for 533MHz-up CPUs.

4) for the looped OGG files note, that SBaGen loads all the file in the
memory at once, so avoid using lengthy looped OGG files.

