libsmacker


A C library for decoding .smk Smacker Video files

Table of Contents


Introduction

libsmacker is a cross-platform C library which can be used for decoding Smacker Video files produced by RAD Game Tools. Smacker Video was the king of video middleware in the 1990s, and its 256-color compressed video format was used in over 2600 software titles.

Smacker files tend to pose a problem for "engine rewrite" projects for legacy games: many used the .smk format for intro videos, cutscenes, and animated textures. Yet the only other open-source solution for playback of .SMK files involves linking against the whole of ffmpeg (or, at least, libavcodec). Many projects offer a workaround of re-encoding video to some other modernized format.

In my opinion, none of these is really optimal. What is needed is a library which supports the minimum feature set from smackw32.dll to get an smk off a disk and the frames / audio into a buffer in the correct order. Hence, libsmacker.


Still frame from SimCopter intro movie (click to play)

Back to top


License

I have deliberately placed this section higher up on the page than usual. Please read this section carefully if you are planning to use libsmacker in your project.

libsmacker, as a re-engineering of a proprietary file format, exists in a sort of legal gray area. RAD Game Tools still offers commercial licensing for the Smacker format: your purchase comes with an SDK, documentation, technical support, and most impartantly a legal ability to redistribute the Smacker run-time in a commercial setting. It is possible, though by no means certain, that libsmacker is infringing on some rights owned by RAD. (It should be noted that libsmacker does not contain any copyrighted binary code.)

For this reason, libsmacker is released under a Creative Commons Attribution Non-Commercial License V2.0. This means, first, that projects using libsmacker must indicate somewhere that they use libsmacker in the code. Also: the Non-Commercial tag means exactly what it suggests: LIBSMACKER MAY NOT BE USED IN ANY COMMERCIAL PROJECT. PERIOD. Non-commercial DOES NOT mean simply "non-profit": commercial includes for-profit, but may also encompass other non-profit activites as well.

IF YOU NEED A COMMERCIAL LICENSE FOR USING SMACKER TECHNOLOGY IN YOUR PROJECT, PLEASE CONTACT RAD GAME TOOLS DIRECTLY. libsmacker does not offer non-commercial licensing. It is hoped that this willful separation will enable RAD Tools and libsmacker to co-exist without legal issue.

Back to top


Usage

Here is some usage info for libsmacker. First, you need to be able to include the library within your project.

All work is done using a special new typedef, "smk". Most functions in libsmacker accept an smk to operate on.

Sample code:

#include "smacker.h"

...

/* file meta-info */
unsigned int w,h,f,cur_frame;
/* microseconds per frame */
float usf;

/* arrays for audio track metadata */
unsigned char   a_trackmask, a_channels[7], a_depth[7];
unsigned long   a_rate[7];

unsigned char *palette_data;
unsigned char *image_data;

smk s;

s = smk_open_file("example.smk",SMK_MODE_DISK);
if (s != NULL)
{
/* print some info about the file */
    smk_info_all(s, NULL, &f, &usf);
    smk_info_video(s, &w, &h, NULL);
    smk_info_audio(s, &a_trackmask, a_channels, a_depth, a_rate);

    printf("Opened file %s\nWidth: %d\nHeight: %d\nFrames: %d\nFPS: %lf\n", argv[1], w, h, f, 1000000.0 / usf);

    /* process first frame */
    smk->first(s);

    /* get frame number */
    smk_info_all(s, &cur_frame, NULL, NULL);

    printf(" -> Frame %d...",smk_info_cur_frame(s));

    /* Retrieve the palette and image */
    palette_data = smk_get_palette(s);
    image_data = smk_get_frame(s);

    /* write out a bmp (see driver.c) */
    dump_bmp(palette_data,image_data,w,h);

    /* Get the audio chunk for this frame from track 0 */
    printf("Audio info for track 0: bit-depth %u, channels %u, rate %u\n",
	    a_depth[0],
		a_channels[0],
		a_rate[0] );

    audio_data = smk_get_audio(s,0);

    printf(" done.\n");

    /* Advance to next frame */
    smk_next(s);

...

    /* Close file */
    smk_close(s);
}

Here is a function reference.

Back to top


Technical

libsmacker is coded almost directly from this reference document: Smacker on multimedia.cx. The library supports all features of both v2 and v4 files, except that Bink Audio Compression (lossy perceptual coding) is unsupported. For most use cases of libsmacker, this is not a serious limitation.

If you need to make some Smacker files, RAD Game Tools provides a compressor within The RAD Video Tools application (Windows only). libsmacker does not and will not support compression. Be sure to uncheck "Use Bink Audio Compression" or you will generate unplayable files. RAD Video Tools is $10 donationware.

Back to top


Downloads

The current version is v1.0, released on March 9, 2013.

Visit the Files area on SourceForge to view all the available files.

Source code is provided via svn on the Sourceforge project page. Please use anonymous SVN checkout / export to obtain the latest version. Click here to visit the Code page.

Back to top


Links

Back to top


Page design by Greg Kennedy.