The DataStreamer processes only one file, the stream file. You create a stream file by preparing a Weaver script file and then submitting that script and all data files to the Weaver tool.
This section describes how to weave chunk files in the following subsections:
The Weaver tool uses a simple proprietary scripting language to control the assembly of chunk files into streams. Some of the information in the script determines the placement of chunks. Other information is written to the stream header, which becomes part of the stream file. Stream header information is used by the application to extract certain information about the stream file.
Basic Weaver script
Weaver scripts consist of lines that are the "rules" the Weaver tool follows when building a stream file from the different chunk files. Each line in a Weaver script consists of a command and, depending on the command, zero, one, or more arguments.
The figure below shows a Weaver script that contains sufficient information to generate a file for use with the NuPlayer example inside the Streaming folder on the Toolkit CD-ROM. Note that not all the commands used in this sample script are necessarily needed by all applications.
Here's some explanation of the commands used in the example script:
writestreamheader-writes a header with information for stream playback to the stream file. Header information comes from the script file itself.
streamblocksize-specifies the size of the stream blocks. Since stream blocks and playback buffers are the same size, it also specifies the buffer size.
streambuffers-specifies how many buffers to allocate for stream playback.
streamerdeltapri and dataacqdeltapri-specifies the difference in priority between your own application and the streamer and data acquisition threads. The threads are discussed in detail in DataStreamer threads and data flow.
preloadinstrument-specifies an instrument to preload for playing audio at a later time. Preload instruments to eliminate disc seeks when audio is played.
audioclockchan-specifies the channel that has the streamer clock.
enableaudiomask-specifies the channel enabled for audio at the beginning of the stream. This is necessary if you use audio in several channels.
subscriber-specifies which subscribers are needed to play back the stream and their priorities relative to the application.
file-specifies the name of a chunk file or stream file and how it is merged into the output stream. The priority argument specifies how the Weaver tool places chunks with identical timestamps into the output stream. The start-time argument specifies the output stream time at which the file's first data appear. You determine exactly where in the output stream a file's data begin.
For more information
A brief discussion of the Weaver script in this chapter is supplemented with more detailed information in later chapters. A manpage for each Weaver script command is included in Weaver Script Commandsof the DataStreamer Programmer's Reference that is part of this volume.
There are sample Weaver scripts on the Toolkit CD-ROM which include code to help you get oriented.
The Weaver is an MPW tool that expects a script file and a number of data files as input and writes out a single stream file. Here's an example of invoking the Weaver tool with a script called NewMovieScript that weaves a video and an audio file.
To make the stream you created with the Weaver tool run smoothly on the 3DO Station, you should first analyze it from your Macintosh. This section first discusses the basic stream format, then looks at an example stream.
Weaver output
A stream file created by the Weaver tool has the following basic format:
File starts with a header describing the stream parameters
Next is a series of fixed-size blocks containing chunks of stream data
Each data chunk consists of a small descriptor followed by data
The descriptor contains fields identifying
data type and a subtype
timestamp
data size
Individual subscribers can extend the descriptor to contain whatever information they require.
Available tools
To look at a stream file, use the dumpstream MPW tool.
For more information
Debugging and Optimization provides more information about optimization techniques for stream files, such as reducing filler.
