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 Mоbile 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.

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.