Note: This document is a work in progress. As an early user
of the SDK, please help make this document more comprehensive by
providing feedback on its contents and suggestions for other information
to include to make the setup process easier. Send comments and suggestions
to sdk@tactile12000.com.

Overview

The Tactile12000 is a Macromedia
Director application with a plugin to handle the audio mixing
and manipulation. To modify the Tactile12000, you may be able to
work only in Director, but for many features you will have to modify
the plugin as well. The plugin requires familiarity with C++ as
well as several additional SDKs. It is possible to change the look
of the interface without doing any scripting, by simply changing
the graphics in Director.

We use Director because it allows us to develop cross-platform
software more easily, since it handles much of the OS and UI programming.
It also allows us to fairly cleanly separate the graphics, UI scripting
and audio programming. It could also be used to distribute the Tactile12000
as a Shockwave movie (we have not released it this way because of
bandwidth requirements, though we have tested it internally).

This document assumes that you have a working knowledge of the
applications described. All developers must be able to use Director
to build the software. Information about using Director itself,
or a C++ development environment is outside the scope of this document.

SourceForge

The Tactile12000 project is hosted on SourceForge.
SourceForge provides a central place for developer information about
the project, including mailing lists, a bug database and source
control. If you would like to contribute to the development of the
software, you can apply to be member of the development group for
it.

License

The Tactile12000 is released under the GNU
Public License, meaning that you are free to modify and distribute
the software. However, as a condition of the license, you must make
the source code freely available for any version of the software
that you distribute. Note that the Tactile12000 makes use of some
third-party libraries that are not covered by the GNU Public License.
You must adhere to the licensing agreements for these libraries.

Getting Started

Downloading the packages

The SDK includes three separate packages:

The Director package includes the Director
movie and casts, as well as binary versions of the Xtra used for
the Tactile12000.

The graphics package includes the Adobe
Illustrator, Adobe Photoshop, and Strata StudioPro files used
to generate the graphics for the UI. You only need this package
if you intend to make visual changes to the user interface. If
you intend to entirely redesign the UI, you might not need these
files, although they may be of interest as a reference.

Downloading third-party SDKs (XDK, XAudio,
DirectX, QuickTime)

If you are modifying the Xtra, you have to download additional
SDKs from other companies before you can modify and rebuild the
Xtra.

Director
8 XDK - this is the SDK for writing Director plugins. You
can use the Director 8 SDK for writing Xtras for either Director
7 or Director 8.

XAudio 3.2.8c
- This is the Windows library used for decoding MP3 files. You
must license the libraries and download from their site. This
is not necessary for Macintosh development.

DirectX 7 -
This is Microsoft's API for interfacing with the sound hardware
on Windows. You may already have the headers and libraries with
Microsoft Visual C++, so you may not have to download the giant
SDK. We are still using the DirectX 7 API for backward compatibility
with users who have not upgraded to DirectX 8.

QuickTime 4
- the Tactile12000 uses QuickTime to play back audio on the Macintosh.
It is also linked in on Windows, but is only used for non-MP3
files.

Setting up your development environment

All developers need to use Macromedia
Director to create the application. The 2.1 release was created
on Macromedia Director 7, but the next release will probably use
Director 8. This means you can use either Director 7 or Director
8 to work on the software. If you are not modifying the Xtra, you
need to copy the binary of the Xtra for your platform into Xtras
folder of your Director installation.

If you are modifying the Xtra, you need to open the project file
in the C++ development environment on your platform - Microsoft
Visual C++ 6 on Windows or CodeWarrior
Pro 4 on the Macintosh. You may have to set up some of the include
paths and library paths for the SDKs that you downloaded. After
building successfully, you must copy the Xtra to the Director Xtras
folder. (more details on building the Xtra are in the next section)

Note: the Windows binary version of the Xtra distributed
in the Director package can only be used with the Tactile12000 application.
If you wish to use it with other Director projects, you need to
license the SDKs used to build in and recompile without the line
of code that checks for the application name.

Director

The Director package is divided into four Director files, and some
supporting files. The Director files include the main movie (t12000.dir)
and three external casts (t12000lg.cst, t12000gx.cst and t12000sd.cst).
Open the main movie in Director to get started; it will find the
external cast files automatically if you leave them in the same
folder as the movie. Make sure that you have copied the DirectSound
Xtra to Director's Xtras folder.

Typically you will spend most of your time modifying the scripts
in the script cast when you are working on the application. The
application makes use of parent-child scripts (Director's mechanism
for doing object-oriented programming). The bulk of the code is
in these parent scripts and other movie scripts. We have tried to
keep the sprite scripts simple. The main objects are in the first
few scripts of the cast (turntable, mixer, channel, sound, etc).

The sound cast (t12000sd.cst) just contains the sample sounds that
are shipped with the application. You can replace these sounds with
your own if you wish.

You can use Director 7 or Director 8 to work on the files. The
next version after 2.1 will probably be using Director 8 so that
we can take advantage of the linked script files feature. That feature
will aid in collaborative development, by making it easier to merge
changes from multiple developers. For now, if you intend to contribute
your changes to the main code base, be careful to mark your changes
well and try to isolate them as much as possible to make the code
merging easier.

Changing the graphics

If you only want to change the appearance of the interface, you
can simply modify the contents of the graphics cast, replacing each
graphic with an alternative one for the same UI element. Make sure
the registration point in the graphic and the placement of the cast
member on the stage are set properly so that the graphics are positioned
properly. For the most part, the scripts are set up to automatically
detect the new location and size of the graphics, and application
should still work correctly. However, this has not been tested before,
so there are probably some fixes necessary in the scripts to get
things to work.

You wil notice that there are quite a few different graphics you
have to produce, and you must be careful to use alpha channels and
JPEG compression where appropriate to support proper compositing
while minimizing the application file size.

If you want to start with the graphics supplied with the SDK, here's
what's in the graphics kit.

t12000.ssp - Strata
Studio Pro 1.75 file with the console, mixer and turntables.
The model is set up with animations for the rotating turntable
platter, moving tonearm, and buttons in the up and down position.
To generate the output, render the entire scene with the buttons
in the up and down positions (and without the sliders), and render
just the turntable area without the tonearm as a QuickTime movie,
and render the tonearm also as a QuickTime movie. Using the QuickTime
player, export all of the frames of the turntable as JPEG files
to import into Director. Then export all of the tonearm frames
as PICT files with an alpha channel. You should be able to use
newer versions of Strata to render the scene. Other 3D software
will probably not import all of the settings of the model properly,
though.

t12000.psd - This is an Adobe
Photoshop 5.0 file. Paste in the output of Strata with the
entire scene with the buttons up and down. You wll then have to
slice and dice the graphic with the appropriate layers on and
off to generate the cast members for Director. One good technique
for making the registration points match up for Director is to
import the entire 640x480 graphic into Director, make copies of
it for each smaller image you need (e.g., the playlist button),
then erase the part of the image that you don't need, using a
white rectangle. The registration point will still be at the same
point as the background, so you can drag the cast member onto
the score and it will automatically line up with the background
image.

playlist.ssp, playlist.psd - these are much simpler Strata and
Photoshop files for the playlist dialog.

roundbutton.psd - this is a Photoshop file for the round buttons
on the lower right of the screen. They have both mouse-over and
mouse-out layers set up.

Most of the UI uses Futura, Futura Condensed, and Futura Bold fonts.
All of the graphics work was done on the Macintosh. We do not know
if it will work exactly the same on Windows.

DirectSound Xtra

Xtras are
plugins to enhance Director's functionality. The Tactile12000 uses
an Xtra to perform the audio mixing and manipulation needed for
DJing. Originally, the Xtra was implemented on Windows many years
ago to take advantage of Microsoft's DirectSound API, which enabled
high-performance mixing. Subsequently, the Xtra was made cross-platform
using Apple's Sound Manager API. When MP3 support was added to QuickTime,
the Xtra was modified to rely more on QuickTime on the Mac instead
of the Sound Manager. In the last couple of releases, Director has
added support for many of the features that the Xtra implements.
However, the Xtra is still necessary for some features of the Tactile12000,
and it allows for continuing to push beyond the functionality of
Director. The Xtra was reorganized as a C++ project for version
2.1.

You will need to modify the Xtra to add support for other sound
formats, to change the low-level behavior of the mixing, or to otherwise
access or modify the audio data. Some features that would require
modification of the Xtra are support for WMA files, RealAudio, equalizers,
sound filters, mix recording, four-channel sound card support, and
BPM counters.

You will need to become familiar with Macromedia's XDK
documentation to understand the Xtra. Their documentation takes
a while to absorb, but hopefully you can get started with just a
basic understanding of the Xtra architecture.

Files

dsxtra.cpp - contains the main class that implements the methods
available from Lingo. In turn, it instantiates one of several
other classes depending on the sound format being read by the
application.

dsdev.cpp - handles DirectSound devices on Windows

dsmp3.cpp - uses the XAudio SDK to read MP3 files on Windows

dsqt.cpp - uses QuickTime to read sound files for both Macintosh
and Windows

Also, if you distribute a different version of the Xtra, please
modify the version resource with a new version number and other
information about your release, as well as the version number in
the source file Xtra.cpp. Also, you should probably update the class
IDs (search for DEFINE_GUID) in dsxtra.h, especially if you are
changing the Xtra interface.

The Xtra source code is maintained in CVS source control on the
SourceForge server. If you intend to contribute your changes to
the main code base, please keep the code clean and well-documented.
Contributors can be given access to the source control database
to add their code.

Windows

MSVC builds the xtra as file dsxtra.x32. You need to copy this
file to the Xtras folder in your Director installation to test your
Xtra. To debug, set your Director executable as the debug executable.
MSVC will warn you that Director does not have debug symbols, but
you can ignore that warning. MSVC will still stop in breakpoints
set in the Xtra code.

The project has both debug and release targets set up. Use the
release build whenever you are making a release of the Xtra or application
(obviously).

Update the project settings to include the paths to the XAudio
SDK and the Director XDK (under Project->Project Settings->C/C++->Preprocessor).

Note: We have had problems stepping through code which has DirectSound
calls. Director and/or the debugger crashes as you step over a call
into the DirectSound library. The workaround is to set breakpoints
explicitly whereever you want to stop, instead of using the "Step
Over" command.

Macintosh

The Macintosh version of the Xtra relies heavily on QuickTime to
read sound files and mix the audio. The built file is named "DSXtraPPC"
and it also needs to be copied to the Xtras folder in your Director
installation.

There is some code which directly uses the Sound Manager to play
the sounds, but it was less reliable and harder to maintain than
the QuickTime code. The Sound Manager code is now primarily used
to handle cast member sounds from Director.

There are two project folders, MACPROJ and MACOPT. The macproj
project builds the debug version of the Xtra and the macopt project
builds the release version. To debug, put an alias to the debug
version of the Xtra in your Director Xtras folder, start the CodeWarrior
debugger, set any breakpoints you want inside the Xtra source code,
then start Director.

You may have to download the Navigation Services SDK and/or the
latest Universal Headers (we are using version 3.3.2) from Apple's
developer web site.

You will also have to update the CodeWarrior project settings to
reflect the path to the Director XDK on your system.

Preparing for Release

Creating a projector

To create the application for distribution, you must create a projector
in Director. First, "Save and Compact" the Director movie
to reduce its file size. Then select the "Create Projector..."
item in the File menu. In the first dialog, select the director
movie. If you want to ship the application as a single file, select
the cast files as well. Hit the Options... button also; make sure
the "Animate in Background" box is checked, as well as
the "Media: Compress" box. The other settings can be set
depending on your preferences for distribution.

If you didn't include the cast files or all of the Xtras with the
projector, you will have to distribute them as separate files along
with the application file. You might want to protect the cast files
using Director's "Update Movies" menu item under the Xtras
menu. However, you must make the unprotected cast files available
as part of the GNU Public License. By releasing the application
with external casts and Xtras, it may be easier to patch a single
part of it in the future.

Testing

Try to test the projector in many hardware configurations and operating
system versions. Also, try testing with different display resolutions
and color depths. Try it with sounds of different formats, and MP3
files of different bitrates. Try MP3 files from different encoders.

Distribution

On Windows, we use the free version of InstallShield that comes
with MSVC to create an installer for the software. We also use WinZip
and WinZip self-extractor to create the downloadable file. On the
Macintosh, we use Stuffit Deluxe
to package the file. No installer is necessary, though you can make
one if you wish.

If you release a new version of the Tactile12000, please contact
us at info@tactile12000.com
and we can post a link to it on the Tactile12000 site. Also, if
your changes are of general interest, you may try to integrate your
changes into the central code base. For this reason, please try
to make your changes clean, well-documented, and easy to understand.