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 Xtra package includes the C++ source files for the DirectSound Xtra as well as projects for Microsoft Visual C++ 6.0 and Metrowerks CodeWarrior Pro 4.
• 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
• dsutil.cpp - utility functions
• win
  • dswin.cpp - Windows-specific functions
  • dssound.cpp - Windows implementation of generic sound class
  • dswave.cpp - WAVE file suppor t for Windows
  • ds3d.cpp - DirectSound 3D suppor t
• mac
  • dsmac.cpp - Macintosh-specific functions
  • dssound.cpp - Macintosh implementation of generic sound class
  • dsaiff.cpp - AIFF file support for the Macintosh (usually QuickTime handles AIFF sounds though)
  • dsmacsnd.cpp - Mac sound support (used for Director cast members)

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.

Questions?

There is a mailing list for Tactile12000 development, tactile12000-development@lists.sourceforge.net. Post any questions about the SDK or the code to that list. You must subscribe to the list before you can post messages to it.