DirectMusic 0.0.1
An incomplete re-implementation of DirectMusic, Microsoft's adaptive soundtrack API for games delivered as part of Direct3D and DirectX
Loading...
Searching...
No Matches
DirectMusic — A re-implementation.

This project aims to re-implement Microsoft's long-deprecated DirectMusic API available in early Direct3D and DirectX versions. It is currently under heavy development at this time and might be unstable for some use-cases.

Soundtracks tested and verified to work (somewhat) correctly:

  • Gothic
  • Gothic II (+ Night of the Raven)

If you tested other games, please let me know. If you own any games with .dls, .sty and .sgt files in the data folders, and you want to contribute, please contact me as well or open an issue on GitHub.

Example

Here's how you play back a segment. This example works on POSIX only since it uses <sys/stat.h> for the file resolver. On Windows, you simply need to replace dm_resolve_file with a Windows-compatible implementation.

#include <dmusic.h>
#include <stddef.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
static void* dm_resolve_file(void* ctx, char const* name, size_t* len);
int main(int argc, char** argv) {
// 1. Create a new DmLoader. The loader is responsible for loading and caching DirectMusic files using a
// user-defined callback function called a "resolver". You really only ever need one for your application.
DmLoader* loader = NULL;
if (rv != DmResult_SUCCESS) {
puts("Creating the loader failed\n");
return rv;
}
// 2. Register a resolver with the loader. A resolver is simply a function which gets a context pointer,
// a filename and returns a memory buffer and its length as an output parameter. The context pointer
// is user-defined, here it's just a path string. You can return NULL from a resolver to indicate that
// the file was not found.
rv = DmLoader_addResolver(loader, dm_resolve_file, "/path/to/your/music/folder");
if (rv != DmResult_SUCCESS) {
puts("Adding the resolver failed\n");
return rv;
}
// 3. Use the loader to obtain a segment. The loader will call your resolvers in order to read in the
// file, and it will then perform some internal magic to load the segment. Since we set the
// DmLoader_DOWNLOAD option when constructing the loader, we don't need to call DmSegment_download
// afterward. Otherwise, you do have to call it.
DmSegment* segment = NULL;
rv = DmLoader_getSegment(loader, "YourSegment.sgt", &segment);
if (rv != DmResult_SUCCESS) {
puts("Getting the segment failed\n");
return rv;
}
// 4. Create a new performance. The performance represents your main playback device. It handles all
// the DirectMusic magic needed to produce music from your segments. You typically only need one
// performance for your application. The second parameter here is the sample rate, defaulted to
// 44100 Hz.
DmPerformance* performance = NULL;
rv = DmPerformance_create(&performance, 44100);
if (rv != DmResult_SUCCESS) {
puts("Creating the performance failed\n");
return rv;
}
// 5. Instruct the performance to play a segment. This will set up the performance's internals so that
// the following call to DmPerformance_renderPcm will start producing music. The performance renders
// music on-demand, so as long as you don't call DmPerformance_renderPcm, you can consider playback to
// be paused. To stop playing music, you can pass NULL as the segment parameter.
//
// The third parameter here is the timing. It tells the performance at which boundary to start playing
// the new segment as to not interrupt the flow of music. The options are "instant", which ignores all
// that and immediately plays the segment, "grid" which plays the segment at the next possible beat
// subdivision, "beat" which plays the segment at the next beat and "measure" which plays it at the next
// measure boundary.
//
// The performance also supports transitions. To play those, use DmPerformance_playTransition and see
// its inline documentation for more information.
rv = DmPerformance_playSegment(performance, segment, DmTiming_MEASURE);
if (rv != DmResult_SUCCESS) {
puts("Playing the segment failed\n");
return rv;
}
size_t len = 1000000;
float* pcm = malloc(sizeof *pcm * len);
// 6. Finally, render some PCM! This will instruct the performance to start processing the underlying
// DirectMusic messages and render the resulting PCM to the output buffer. In this case it will
// render 1000000 stereo samples which is 500000 samples per channel.
//
// This will advance the internal clock for as many ticks as required to render the requested number
// of samples. No more, no less.
rv = DmPerformance_renderPcm(performance, pcm, len, DmRender_FLOAT | DmRender_STEREO);
if (rv != DmResult_SUCCESS) {
puts("Playing the PCM failed\n");
return rv;
}
// 6.1. Write out the PCM data to some place where we can access it later. This could also just be some
// audio output device or another library.
FILE* fp = fopen("output.pcm", "w");
if (fp == NULL) {
puts("Opening the output file failed\n");
return -1;
}
(void) fwrite(pcm, sizeof *pcm, len, fp);
(void) fclose(fp);
// 7. Don't forget to clean up after yourself.
free(pcm);
DmPerformance_release(performance);
return 0;
}
static void* dm_resolve_file(void* ctx, char const* name, size_t* len) {
char const* root = ctx;
// 1. Concat `root` and `name` to produce the final path. If a slash is missing
// at the end of `root`, add it.
size_t root_len = strlen(root);
size_t name_len = strlen(name);
int miss_sep = root[root_len - 1] != '/';
char* path = malloc(root_len + name_len + 1 + miss_sep);
memcpy(path, root, root_len);
memcpy(path + root_len + miss_sep, name, name_len);
if (miss_sep) {
path[root_len] = '/';
}
path[root_len + name_len + miss_sep] = '\0';
// 2. Check if the file we want to open actually exists. If it doesn't, return NULL.
struct stat st;
if (stat(path, &st) != 0) {
free(path);
return NULL;
}
// 3. Read in data from the file.
FILE* fp = fopen(path, "re");
if (fp == NULL) {
free(path);
return NULL;
}
void* bytes = malloc((size_t) st.st_size);
*len = fread(bytes, 1, (size_t) st.st_size, fp);
(void) fclose(fp);
free(path);
return bytes;
}
DmResult
Possible operation result values.
Definition dmusic.h:46
void Dm_setLoggerDefault(DmLogLevel lvl)
Set a default logging function.
@ DmResult_SUCCESS
The operation completed successfully.
Definition dmusic.h:48
@ DmLogLevel_INFO
The log message is informational.
Definition dmusic.h:187
struct DmLoader DmLoader
Represents a DirectMusic Loader.
Definition dmusic.h:299
DmResult DmLoader_create(DmLoader **slf, DmLoaderOptions opt)
Create a new DirectMusic Loader object.
DmResult DmLoader_getSegment(DmLoader *slf, char const *name, DmSegment **segment)
Get a segment from the loader's cache or load it by file name.
void DmLoader_release(DmLoader *slf)
Subtract one from the reference count of a loader.
DmResult DmLoader_addResolver(DmLoader *slf, DmLoaderResolverCallback *resolve, void *ctx)
Add a resolver to the loader.
@ DmLoader_DOWNLOAD
Automatically download references.
Definition dmusic.h:377
@ DmLoader_DEFAULT
Default options for loader objects.
Definition dmusic.h:380
DmResult DmPerformance_playSegment(DmPerformance *slf, DmSegment *sgt, DmTiming timing)
Schedule a new segment to be played by the given performance.
void DmPerformance_release(DmPerformance *slf)
Subtract one from the reference count of a performance.
struct DmPerformance DmPerformance
Represents a DirectMusic Performance.
Definition dmusic.h:306
DmResult DmPerformance_renderPcm(DmPerformance *slf, void *buf, size_t num, DmRenderOptions opts)
Render a given number of PCM samples from a performance.
DmResult DmPerformance_create(DmPerformance **slf, uint32_t rate)
Create a new DirectMusic Performance object.
@ DmTiming_MEASURE
Timing flag indicating start at the next possible measure boundary.
Definition dmusic.h:490
@ DmRender_STEREO
Render flags to request stereo PCM rendering.
Definition dmusic.h:476
@ DmRender_FLOAT
Render format flag to request rendering of float samples.
Definition dmusic.h:473
struct DmSegment DmSegment
Represents a DirectMusic Segment.
Definition dmusic.h:292
void DmSegment_release(DmSegment *slf)
Subtract one from the reference count of a segment.

Contact

If you have any questions, or you just want to say hi, you can reach me via e-mail (me@lmichaelis.de) or on Discord either via DM but preferably in the Gothic VR and GMC servers (@lmichaelis).