Welcome to DTPKDump!

DTPKDump is a utility designed for use with Sega Dreamcast and NAOMI games. It can be used to analyze the internals of DTPK files, extract out the raw samples, and/or inject samples. It is still at a power user level: it will likely require you to do a little bit of work and thinking to figure out how to do what you want to do. But you should be able to do most common tasks.

Note that DTPKDump as an audio tool operates with the raw sample data. It deliberately does not account for playback effects such as pan, reverb, chorus, and other tweaks. You can use KingShriek's dsfdtpk to listen to and extract post-processed audio.

DTPKDump is under active development in 2024. This is a complex area, so I have tended to take breaks to gather my thoughts. I'm not done: I'll remove these and other "updates are going to happen" notices once I'm done. You can find new releases at https://zachd.com/dptk .

If you're a developer or romhhacker or just curious, the source code can be found at https://github.com/Preppy/dtpk . If you figure out ways I am dumb or can improve, please let me know. This is my first work in Python and I'm sure it's a little raw.

Getting Started

1. Download and install Python. I have been using Python version 3.12 but trying to avoid using any version-specific extensions. Note that the AIFF support in Python may be removed in Python 3.13, so when/if that ever comes out you probably do not want to upgrade.
2. Download the current version of the DTPKDump script.
3. Download and extract out the ROM for the game you care about. Save a copy of the game ZIP "just in case".
4. Download whatever audio content you want to use and/or inject.
5. Process the audio as you want using an audio tool such as Audacity or the old Microsoft Sound Recorder. DTPK solely supports mono or stereo 8bit or 16bit PCM audio. The intended range for DTPK is 4000Hz to 23000Hz, although it does support up to about 48000Hz. For space reasons, using mono is ideal. For space reasons, sticking to lower frequencies such as 11025 or 22050 is also ideal. Audio in DTPK can be imported as either uncompressed PCM WAV or uncompressed PCM AIFF. Frankly PCM WAV is a lot easier to work with and generate.
6. Figure out what sample number you want to update.
7. Use a super easy command line such as: python dtpkdump.py PL18_VOI.BIN -splicepcm 12 newsample.wav -o PL18_VOI_new.BIN That will open up PL18_VOI.BIN, changing the sample at slot 12 to "newsample.wav", saving the results as PL18_VOI_new.BIN.
8. Once you have the results you like, copy that new DTPK file back to the target disc image. Repack the ROM.
9. Load the image into your favorite emulator/console and have fun!

Program Functions

This section covers all the options available in the DTPKDump interface and is probably worth a read at least once.

**** File Inspection ****

-showinfo

Shows the entire layout of the DTPK file. DTPKDump does not show unchanged/stock values for Playback Data entries unless you also use the -v flag. If you just want to look at one or more of the individual chunks of the file, use one of the following options instead.

-showheaderinfo

Display detailed information about the header. A DTPK header contains information about the location of the relevant DTPK chunks, if they are present.

-showcombinationinfo

Display detailed information about the Combination data.

-showprogramdefsinfo

Display basic information about the program definitions data. While we know the general structure of this chunk, the contents are unknown.

-showunknowninfo

Display basic information about the unknown table. I'm uncertain what data is within this chunk.

-showtrackinfo

Display information about the track data. This is where the SONG or TRACK data is stored that defines how any given composition is formed. Note that a System Event : Control Switch : NULL track is normally just being used as a placeholder to help ensure the compositions are aligned numerically in a way that the game expects. Compositions that want to include samples during playback do so by referencing them via Sample Playback Data (SPD) entities.

-showfulltrackinfo

Display detailed information about the track data. (We gloss over some aspects if you're just using -showtrackinfo .)

-showplaybackinfo

Display detailed information about the sample playback data. The Sample Playback Data defines how any given sample is to be played back, notably including such important aspects as playback rate (frequency). Note that we do not show stock settings by default: use -v if you want those too. DTPK can do some very interesting things in these settings, but most games won't do much with them.

-showeffectsinfo

Display detailed information about the sample effects data. This chunk handles additional pan, volume, reverb, fade, chorus, pitch, etc settings.

-showsampleinfo

Display detailed information about the samples. Sample waveform data is stored as either PCM or Yamaha AICA ADPCM data. The channels are stored sequentially, not interleaved. The descriptive data in this chunk solely describes waveform aspects, since the actual rendered playback information is track-dependent.

-v

For use when showing Playback definition data: show all the settings even if are stock/unchanged values.

**** Audio Extraction ****

-dumpadpcm

Extract out all ADPCM samples to raw Yamaha AICA ADPCM files (usable in Awave Studio).

-dumpaiff

Extract out all PCM samples to PCM AIFF files (may not work for strange playback rates).

-dumpaiffall

Extract out all samples to PCM AIFF files (may not work for strange playback rates).

-dumppcm

Dumps each PCM sample to its own PCM WAV file.

-dumppcmall

Extract out all samples to PCM WAV files (may not work for strange playback rates).

-extractall

Extract out all samples. PCM samples will be extracted to WAV, YADPCM samples will be extracted to ".yadpcm", which is just raw Yamaha AICA ADPCM chunks.

-wavconv

Extract out all samples (both YADPCM and PCM) as PCM WAV files.

**** Audio Injection ****

-splicepcm

DTPKDump replaces the sample at that specified sample bank slot with the sample you told it to.

-spliceadpcm (NUM) (FREQUENCY) (FILENAME)

replace sample NUM in the DTPK with the specified YADPCM file. Requires -out.

-spliceaiff (NUM) (FILENAME)

Replace sample NUM in the DTPK with the specified AIFF file. AIFF files must be uncompressed 8bit or 16bit. Requires -out.

-splicepcm (NUM) (FILENAME)

Replace sample NUM in the DTPK with the specified PCM WAV file. WAV files must be PCM 8bit or 16bit. Requires -out.

**** Other Options ****

-addtrack (GROUP) (SPD)

Add a new track to GROUP using SPD. The GROUP value can be either absolute index or group descriptor (ex: a920). Use special SPD value "0xbad" if you want to inject a NULL/empty track. Requires -out.

-addplayback (NUM) (FREQUENCY)

Add a new SPD using sample NUM played back at FREQUENCY. Requires -out.

-out (FILENAME)

Save the updated DTPK file as FILENAME. Requires one of the splicing options.

-options

Shows the expanded list of options. Normally if you just run "dtpkdump.py" by itself it shows a shorter quick/easy option list.

-reassemble

Rebuild the file (to test reassembly logic). Requires -out. Useful for me to ensure that dtpkdump is able to reconstruct the file correctly.

While DTPKDump can work with DTPK files, the first question is what files in the game image are DTPK files. To find those we can open a command prompt, go to the directory where your game ROM is, and then run:

I'm getting audio glitching while playing the game!

Most likely you are blowing past the audio memory on the Dreamcast/NAOMI. There is not a lot of space to work with, so downsample your audio as needed.

Information that is useful to share:

• What Python version you're using
• What version of what game you're trying to use
• What file you're working with
• What went wrong