DivX H.264 Encoder Alpha 1 & Tutorial

The second package to be released from Project Rémoulade is an alpha version of the DivX H.264 Encoder. Complementing the DivX H.264 Decoder, this multithreaded encoder produces high definition H.264 video bitstreams that are compatible with the draft profile for DivX 7 H.264 HD video. The encoder is a command line utility and accepts input from raw AVI files as well as the AVISynth frameserver.

View our tutorial for the DivX H.264 Encoder

An introduction to the DivX H.264 Encoder

In this article we'll start with a walk-through of using the command line encoder. We'll cover everything from encoder installation to the third-party software nedeed to create and play MKV files, tools for video processing, some of the constraints in the draft DivX 7 H.264 HD video profile and some tips on customizing your experience with the encoder for easier, more automated multipass encoding. Our guide should be very easy to follow so grab a cup of tea and let us teach you the basics! In the near future we'll also discuss the draft profile in more detail for those who are interested.

Contents

• 1. Installing the DivX H.264 Encoder Alpha 1
• 2. Installing third-party software
• 3. Creating an AVISynth script
• 4. Using the DivX H.264 Encoder with your AVISynth script
• 5. Bitrate, rate control, encoding modes and more
• 6. Preparing MKVMerge
• 7. Writing the H.264 video bitstream into an MKV container
• 8. Playing the MKV file

• Known issues for DivX H.264 Encoder Alpha 1
• How you can help us

1. Installing the DivX H.264 Encoder Alpha 1

Setting up the encoder is very straightforward. Members of the Project Rémoulade group who are signed in to their DivX Labs accounts can download the installation package. If you're not yet a group member please create a DivX Labs account and contact us with some information about yourself, any experience you have with video software and hardware, your basic system specs (OS, CPU, graphics card), and any related projects or forums you are involved in. Space is limited in this group and we prioritize applications from members who take the time to tell us about themselves.

After downloading and launching the installation package you should see the following screen:

Click to enlarge

You should note the installation folder location because this is where the command line utility will be installed. A shortcut named Encoder Console that opens a command window at this location is automatically added to your Start menu Programs folder under DivX\DivX H.264 Codec CLI . Launch the Encoder Console and type divx264 -help to see the list of arguments that can be passed to the encoder. If you aren't used to working with command line utilities don't worry if it looks a little complicated. We'll walk you through it in a moment, but first let's also install a few other components you'll need.

2. Installing third-party software

This alpha version of the encoder outputs raw H.264 video bitstreams. To transform these bitstreams into video files that will play in your favorite media players you'll need some additional software to write them into an MKV container after encoding, and then during playback something to read the bitstream back out of the container and an H.264 decoder to transform the bitstream back into actual video. We also recommend additional software to serve video into the encoder; we'll explain that more in step 3. First, let's get everything installed!

• AVISynth 2.57 [Homepage]
  
  AVISynth is a script-based frame server. You will use it to prepare your source video for encoding and to serve it as input to the H.264 encoder. During the AVISynth installation it is convenient (but not required) to associate .avs files with Notepad via the option on the component selection screen.
  
  
• VirtualDub [Homepage]
  
  VirtualDub is a video processing application. You will use it to preview the output of your AVISynth scripts. Simply extract the .zip archive into any new folder. No installation process is required.
  
  
• MKVToolnix [Homepage]
  
  MKVToolnix is a package of tools for working with MKV containers. You will use it to write the raw H.264 bitstream that the encoder creates into an MKV file.
  
  Note: You may want to jot down the installation path for MKVToolnix that displays during installation. Later we'll explain how to use this information to make MKVToolnix more convenient to use.
  
  
• Haali Media Splitter [Homepage]
  
  Haali Media Splitter is a DirectShow filter capable of parsing MKV containers. Once installed it can be used automatically by any DirectShow media player to read data streams from MKV files. This includes most players for Windows.
  
  
• DivX H.264 Decoder Beta 2 [Homepage]
  
  The DivX H.264 Decoder is a DirectShow filter that decodes H.264 video streams. Once installed it can be used automatically by any DirectShow media player to decode H.264 video bitstreams ready for display.
  
  Note: To download the DivX H.264 Decoder you must be a member of the Project Rémoulade group and signed into your DivX Labs account. The download link will then appear on the Project Rémoulade homepage.
  
  
• MONOGRAM GraphStudio [Homepage]
  
  MONOGRAM GraphStudio allows you to build, view, edit and run DirectShow filter graphs. We'll use it to examine how the MKV files we create are rendered and to access settings for the DivX H.264 Decoder. No installation of GraphStudio is required. Simply save the file to disk.

3. Creating an AVISynth script

The first step in encoding H.264 video is to prepare the input for the encoder. It's best to use AVISynth because we can easily work with various file types including compressed AVI files which the alpha encoder does not support natively, and make any necessary adjustments to the video before encoding it.

AVISynth is a scripted frame-serving engine. When an application that supports AVI files, such as VirtualDub, opens an .avs file (.avs is the file extension for AVISynth scripts) the AVISynth engine loads and creates the source video on the fly according to the script you've written to generate it. AVISynth scripts can be as simple as a single line that loads a single source file, or as complex as necessary to produce professional-grade video effects using multiple sources and dozens of freely available plugins. Let's start with a very simple script to check that AVISynth is installed correctly.

Start Notepad and enter the following:

Save this file with a .avs extension instead of the default .txt extension. If you can't see the file extension when you save the file turn off the option to "Hide extensions for known file types" in the Windows Folder Options control panel under the View tab. Next, start VirtualDub and drag your .avs file onto the VirtualDub program window. You should see a video that is ten seconds long displaying information about the installed version of AVISynth:

Click to enlarge

This video has been generated by AVISynth's internal filter named Version, which you used in your .avs script. Find information about all of AVISynth's built-in filters on the avisynth.org Internal Filters wiki page if you're interested or need help. We'll briefly cover each of the filters that are key to getting started in this guide. Don't worry about the second video display that appears in the VirtualDub window for now, it's only useful when you apply additional processing in VirtualDub and that's not part of this tutorial.

AVISynth has several source filters built-in that allow it to input many file types. We'll use either AVISource or DirectShowSource. Modify the following script by uncommenting one (and only one) of the "source" lines and changing the filename to the name of your input file:

Click to enlarge
Download this sample script
(Note: After downloading change the file extension to .avs)

Notice in the screenshot that we've turned off Word Wrap and enabled the Status Bar using Notepad's Format and View menus respectively. Should AVISynth report an error on any particular line, this can make finding the problem easier. Also notice that this time around we're using the "return" instruction to explicitly instruct the AVISynth engine to pass our clip MySource to VirtualDub. Because we're assigning our source to the clip variable MySource AVISynth doesn't implicitly know that this is what we want to return to the host application.

As before, drag the .avs file onto the VirtualDub program window to test the script. If all is working you should see your source video!

The next thing we need to know is the frame rate of the video and picture dimensions. To ensure reliable playback on a wide range of consumer electronics devices the draft profile for DivX 7 places constraints on these properties, requiring that the picture dimensions be at least 320x240 pixels with width and height each being multiples of eight, that the picture dimensions do not exceed 1280x720 if the frame rate is greater than 30hz, and that the video has the exact equivalent of one of the following Rate/Scale combinations:

Let's go back to our first .avs script that simply used the built-in Version filter to display the version of AVISynth that is installed. Because everyone following this tutorial has access to the same Version filter we'll use this as a video source for the next few examples. Of course you could substitute any AVISource or DirectShowSource that you like.

Open the simple Version() script again with VirtualDub and choose File information... from the File menu. Notice that the frame size is 436x80. This gives us two problems to deal with: The width is not a multiple of eight (436 divided by 8 is not a whole number) and the height is less than 240 pixels. If we divide the width by eight we get 436 / 8 = 54.5 . Rounding up to the nearest whole number and multiplying by eight gives us the nearest larger resolution: 55 * 8 = 440 pixels. So we need to add 4 pixels to the height of the clip and 160 pixels to the width to meet the profile constraints. We can use AVISynth's built-in AddBorders filter to pad the frame with a black border. Let's add 2 pixels to the top and bottom and 80 pixels to the left and right of the frame using the color black:

If you drag this new script onto VirtualDub you can see how AddBorders has changed the video:

Click to enlarge

Note that if we had wanted to avoid adding pillarboxing AVISynth gives us several alternatives including cropping and resizing. You can see examples of these in the following sample:

Click to enlarge
Download this sample script
(Note: After downloading change the file extension to .avs)

Okay, so now we know several methods of manipulating the picture dimensions to fit our needs. What about taking care of the frame rate? The approximate frame rate of the video is calculated as a fraction, or in other words ~fps = numerator/denominator. The numerator is also referred to as the "rate" and the denomninator as the "scale". Certain rates are easy to specify exactly. For example, 24fps can simply be given as 24/1. Others are trickier depending on the precision required. For example, you might find that a source loaded with AVISource or DirectShowSource has a frame rate of 29.97 fps calculated from a rate/scale of 5000000/166833 = 29.970089[...] fps which is actually different to the DivX 7 profile constraint of 30000/1001 = 29.970029[...] fps. The draft profile is strict in this regard so as to ensure accurate presentation of content across many device types. Note that equivalent substitutions are permitted, for example 120000/4004 = 30000/1001 = 29.970089[...] fps.

Sound tricky? It really isn't. Let's examine the frame rate of Version() by applying AVISynth's internal Info filter:

Click to enlarge
Download this sample script
(Note: After downloading change the file extension to .avs)

Click to enlarge

As you can see from the screenshot, Version() already has a valid rate/scale of 24/1 = 24.0000 fps so there's no need to make any changes. However, what if you have to deal with an incompatible rate?

Let's think back to our earlier example of a source at 29.97 fps using a rate/scale of 5000000/166833 instead of the profile requirement of 30000/1001. That's a difference of only (5000000/166833) - (30000/1001)= ~0.00006 fps, and over the length of a two hour long video it results in a difference in duration of only 0.00006 fps * 7200 seconds = ~0.436 frames, or approximately 0.463 frames * (1 second / 29.97fps) = ~15ms total, which is probably not even worth worrying about. You could simply override the rate/scale in AVISynth without adjusting the audio or video at all. But what if the source frame rate was not close to one of the rates in the spec, or you wanted to ensure "perfect" sync over a very long video? AVISynth provides a few of ways to handle this. Let's look at two of them:

• ChangeFPS duplicates or removes frames as necessary to attain the new frame rate without changing the clip duration. This is the easiest and, in many cases, the cleanest way to change the frame rate because no adjustment to the audio is necessary. There are no changes in pitch, sample rate, duration or sync to worry about. Keep in mind that in our example, adapting the rate/scale resulted in less than half of one frame of skew over two hours, so if you are simply adapting for a permitted rate/scale it is unlikely that many frames will be duplicated or removed. Duplicate frames can also be processed extremely efficiently by the encoder.
  
  
• AssumeFPS simply speeds up or slows down the video. This technique is more complex in that it actually affects the duration of the video. If you are also processing audio through AVISynth, either as part of the original video source or by using some combination like WAVSource and AudioDub then AVISynth will also raise or lower the audio sampling rate as necessary to maintain sync. This implies a change in pitch and the audio may end up at a non-standard sampling rate. You can later use ResampleAudio later to resample the audio back to a standard rate (e.g. 44.1Khz or 48Khz), or instead use TimeStretch to stretch the audio clip to the new video duration without changing the pitch. If you were not passing audio through AVISynth, which is sometimes the case, you would have to manually adapt the audio before encoding it to ensure it remained in sync.
  
  

Both ChangeFPS and AssumeFPS accept a numerator (rate) and denominator (scale) as arguments. The following sample script shows some examples of changing the frame rate. As you can see using ChangeFPS() is very simple:

Click to enlarge
Download this sample script
(Note: After downloading change the file extension to .avs)

Now you know how to adapt any source to become valid input for the encoder and you can see why even though the DivX H.264 Encoder can encode raw AVI files directly, it's still very handy to be familiar with the basics of AVISynth. It offers such useful functionality that you may always want to feed AVS files to the encoder (this is exactly what many of the community-created graphical user interfaces do). To complete this part of the tutorial, create an .avs script for a source file of your choosing that returns a video with frame rate and picture dimensions that fall within the constraints of the draft DivX 7 HD profile. Audio is optional because the H.264 encoder is not directly concerned with it.

4. Using the DivX H.264 Encoder with your AVS script

Launch the Encoder Console shortcut that was created in you Start menu Programs group under DivX\DivX H.264 Codec CLI when you installed this alpha software. You'll see the following:

Click to enlarge

The shortcut runs a batch script that automatically adds the installation folder to the PATH environment variable for this particular console window, allowing you to run the encoder conveniently from any directory. Later we'll explain how to do the same for MKVToolnix. Although this tutorial isn't intended as a guide to the Windows command interpreter here are a few essentials to help you navigate the file system just in case you aren't already familiar with it:

Change directory to the location where you stored the .avs script that you want to encode or alternatively your raw AVI file if you chose not to make an AVISynth script for it. Type the following command to see the form of the DivX H.264 Encoder command line:

DivX264 -help

You can also download -help as a text file for easier viewing. In command line documentation it's convention to use square brackets to indicate parts of the command line that are optional, and angular brackets to indicate parts of the command line that are mandatory. You can see that the basic usage is as follows:

Usage: [options] -i <input file> -o <output file>

You must specify the name of the input and output file using -i and -o respectively, otherwise you'll get an error. You can also precede the -i and -o arguments with one or more options as detailed by -help. For example, we could prefix them with the -br argument to specify "Target bitrate in kbps". Because -br is documented as "-br <int>" if we specify -br we must also specify an integer value following it, which will be the target bitrate.

Let's start with something simple: a one pass encoding using the default options. The encoder will automatically choose a reasonable bitrate based on the resolution and frame rate of the source file unless we specify one, which is fine for our initial experiment. Enter the following, substituting the name of your source file and the output filename that you want:

DivX264 -frames 100 -i "MySource.avs" -o "Output.264"

The encoder should start running. If you get an error message check that the frame rate and picture dimensions meet the draft DivX 7 profile constraints. The file extension ".264" is commonly used to denote raw H.264 video bitstream, which is what the alpha encoder outputs. We will later use MKVToolnix to write this bitstream into an MKV container file to allow DirectShow media players to play it back. Notice that we've added the option "-frames 100" to the command line. This tells the encoder to stop after it has encoded the first 100 frames from the source file, which is useful when you're first experimenting because you don't have to wait for it to finish encoding an entire file. When you have a command line you are happy with simply remove this argument.

5. Bitrate, rate control, encoding modes, and more

Before moving on to the topic of writing MKV containers, let's cover a few of the encoder's important options. We've already mentioned use of -br for setting the bitrate, but let's elaborate further because it's critical for balancing quality against file size. The bitrate tells the encoder how much data it can use per second of video on average, over the entire duration of the video. This means that if you specify a bitrate of 4000kbps, for example, the encoder may use more than 4000kbps for some parts of the video and less for others depending on the relative complexity of any particular sequence of frames, but on average it will aim to spend 4000kbps over the entire file. Keep in mind that the rate is given in bits per second, not in bytes per second, which is what you're likely used to dealing with. There are 8 bits in every byte, so you can simply divide and multiply by 8 if you need to convert between the two. For example, if you have a video that is an hour and a half long and you encode it at 2000kbps the final size of the raw bitstream will be approximately 1.5 hours * 60 minutes * 60 seconds * (2000,000 / 8) = 1,350,000,000 bytes, or approximately 1287MB (there are 1,048,576 bytes in one megabyte). The MKV container will add a small overhead on top of this rate, as will any accompanying audio.

There are many bitrate calculators available online for free. Use your favorite search engine to find one. Let's work through one example to illustrate the mathematics. In our example we want to encode an hour long video in 720p @ 25fps with 128kbps audio and fit everything inside a 1GB file. Which bitrate should we use?

• The first thing to realize is that bitrate calculations for target file size care only about two things: How long is our video, and how much storage capacity do we have? The fact that the video is 720p and 25fps is irrelevant to hitting a target file size, although using a bitrate that is too low for the video in question will of course result in degraded quality.
  
  
• Start by calculating the duration of the file: 60 minutes * 60 seconds = 3600 seconds.
  
  
• Next, calculate how much storage is available: 1GB = 1,073,741,824 bytes * 8 bits = 8,589,934,592 bits / 1000 = ~8,589,934 kilobits.
  
  
• Then subtract the storage that will be used by audio (@128kbps): We have 3600 seconds * 128 kilobits = 460,800 kilobits of audio to store. That leaves us with 8,589,934 kilobits - 460,800 kilobits = 8,129,134 kilobits for video.
  
  
• The video bitrate will therefor be 8,129,134 kilobits / 3600 seconds = ~2258kbps, minus a very small amount for the overhead of the MKV container we will later store everything in.

Our command line might look like this:

DivX264 -br 2258 -i "MySource.avs" -o "Output.264"

When it comes to creating high-quality video bitrate is only one part of the equation. In our example the encoder has an average bitrate of 2258kbps to work with, but we know that depending on how the picture complexity varies throughout the file it may allocate more bits to some frames than to others. The algorithm that makes such allocations must therefore affect the overall quality of the video. This algorithm is called the rate control, and there are two rate control modes available in the alpha encoder: 1-pass and Multipass.

1-pass mode is the default and causes the encoder to manage data allocation based on the complexity of the incoming sequence of frames. This allows the rate-control to spend bits fairly appropriately as long as the video complexity remains fairly consistent.However, because the encoder can't look ahead (it's making only one pass over the video), rapid changes in video complexity can lead it to speculate about the rate allocation in a suboptimal manner. For example, imagine a situation in which the encoder is processing a panning shot of a landscape. This is probably a low-motion sequence that is very easy to motion compensate leading to high picture quality with only an average bitspend. Then imagine an action scene immediately following. The image texture is now changing extensively from frame to frame and motion compensation becomes more difficult. After encoding one or two frames of this new sequence at the same quality as the landscape sequence the data rate has spiked due to the increased video complexity. The encoder knows it only has a certain average bitrate to work with and that it must also limit rate spikes so that the output bitstream can be played back smoothly by decoders in consumer electronics devices. As the encoder is still unable to predict what will happen in upcoming frames, it may have to react by reducing the data rate sharply in order to avoid rate spikes and to maintain its bitrate budget, in turn causing noticeable variations in the picture quality.

Multipass mode attemps to work around this lack of foresight by breaking the encoding process down into at least two passes. During the first pass the encoder analyzes the source video complexity and stores this information in a statistics file. No video is output during the first pass. Later, the encoder is started again to perform the actual encoding. During this second pass the statistics file that was created on the first pass is loaded to inform the rate control algorithm of the complexity of every frame of video that it should expect to encode, and this enables the rate control to efficiently distribute the available bits throughout the video in a manner that improves quality consistency. The downside to multipass encoding, of course, is that you have to pass the video through the encoder at least twice, which can take a long time, depending on your source file and encoder settings.

There is nothing special to do to perform a 1-pass encoding. Let's look at the command line for a 2-pass encode using our previous example again. To run the first pass we could use:

DivX264 -br 2258 -npass 1 -sf "MyStats.dat" -i "MySource.avs" -o "Output.264"

Immediately following the completion of this first pass we could then use:

DivX264 -br 2258 -npass 2 -sf "MyStats.dat" -i "MySource.avs" -o "Output.264"

As you can see, multipass encoding is no harder than 1-pass encoding, it just takes longer.

One of the most frustrating aspects of performing a multipass encoding can be waiting for the first pass to finish so that you can start the second pass, and an easy way to solve this problem is to use batch scripts to do this work for you. A batch script is simply a plain text file (as Notepad would create) with a .bat file extension instead of a .txt extension. By entering both commands into a batch file and then typing the name of the batch file into the console window the commands will be executed automatically one after the other by the command interpreter. You can easily create batch scripts that are reusable. For example, take a look at the following batch script:

Click to enlarge
Download this sample script
(Note: After downloading change the file extension to .bat)

This script makes use of the way the command interpreter passes command line arguments into the batch script so that you can pass the script any bitrate and any source file name on the command line instead of editing the script for every encoding. Inside the script the first argument becomes %1, the second argument becomes %2, and so forth. So if you called the batch script this way:

MultipassSample.bat 2258 Sample

.. the command interpreter would run the following DivX264 commands:

DivX264 -br 2258 -npass 1 -sf "Sample.dat" -i "Sample.avs" -o "Sample264"

DivX264 -br 2258 -npass 2 -sf "Sample.dat" -i "Sample.avs" -o "Sample.264"

You can create a second batch script that calls the MultipassSample.bat script for many source files in a row using the Call command. If you're interested, you can also look at a more advanced sample that handles both one pass and multipass encoding, prints some status information to the console and does some basic error checking. The syntax for the advanced sample is:

AdvancedEncodingSample.bat <passes> <bitrate> <filename>

Of course, batch scripts are just one way to make use of the encoder. You could also design a graphical front-end application using anything from VisualBasic to C to .Net.

The last encoder option that we'll cover in this tutorial is the algorithm quality optimization mode. Variations on the algorithms and bitstream features in use can exist inside the encoder, as well as settings that control how much effort the encoder expends trading off the efficiency of the many decisions it can make while encoding. The -aqo option controls whether the encoder is configured to be faster at some expense of efficiency or vice versa. Remember that the bitrate is the largest factor when it comes to quality and the rate control method determines how the available bits are allocated. The -aqo mode determines how much time the encoder spends ensuring it is making the most efficient use of those bits. In the alpha encoder there are three -aqo modes available:

• -aqo 0
  Fastest mode, least efficient.
  
  
• -aqo 1
  Balanced mode, best trade-off of speed versus efficiency. This is the default mode.
  
  
• -aqo 2
  Highest quality mode, slowest but most efficient.

For example, to use the highest -aqo mode you could write:

DivX264 -br 2258 -aqo 2 -i "Sample.avs" -o "Sample.264"

6. Preparing MKVMerge

The last two steps of this tutorial will explain how to write our raw H.264 video bitstream into an MKV container. This is necessary because in order for DirectShow media players to play the video they need to recognize the media type, stream properties such as resolution and frame rate and other information that makes navigation possible. This information is all provided by the source splitter (in our case the Haali Media Splitter), which parses the information from the MKV container file when DirectShow calls upon it to do so, enabling the DirectShow media system to construct a filter graph that contains all the decoders and transforms necessary to render the file. Most players won't play the raw bitstream directly. We can also add audio to the MKV container file if we want. But first, we have a small problem to overcome.

Earlier in the tutorial, we explained that the batch script responsible for running the Encoder Console you've been using adds the encoder installation directory to the PATH environment variable so that you can run the encoder from any directory. Let's now explain what that means.

Every running process under Windows (and DOS, for that matter) has a set of "environment variables" associated with it. These are just string variables that contain information that let applications understand the environment they're running in. In the console window, type the following command:

Set

You will see a long list of variable names and their associated data appear on screen. Some of these are set by Windows as global environment settings, others are specific to the user currently logged into the system, and some may be set by applications or batch scripts. If you looked at the advanced batch script in section 4 you may have noticed it uses the Set command to temporarily store information about the number of passes remaining in an environment variable while the script runs. The environment variable we're interested in right now is called PATH. Type the following to see the value of the PATH environment variable:

Echo %PATH%

You will notice that PATH is a long list of directory names separated by semicolons. If you're running the command from the Encoder Console window, you'll also see that the first folder name is where the encoder was installed to. The batch script that runs the Encoder Console adds this automatically when it runs. The command interpreter uses this list of directories to look for programs and scripts when you type the name of a program as a command and it can't be found in the current directory. This is why you can type the command divx264 from any directory when you are using the Encoder Console; the interpreter searches for it using the PATH list and locates the program. But try running MKVMerge, the utility from MKVToolnix that we want to use:

MKVMerge

You'll receive an error message because the interpreter doesn't find MKVMerge in the current directory, nor can it locate it on the PATH list. There are two ways to solve this problem:

1. Prefix the MKVMerge command with the complete installation path for MKVToolnix every time we want to use it.
   
   
2. Add the installation folder for MKVToolnix to the PATH environment variable.

Explicitly specifying the full path to MKVMerge on every use is cumbersome and tedious. Instead, we can automatically add this folder to the PATH variable when the Encoder Console starts, just as the path to divx264 is also added. To do so, we'll edit the batch script that was installed along with the alpha encoder. Use Windows Explorer to navigate to the DivX264 installation folder. This is the folder that is the current working directory when you first open an Encoder Console window. You will see a batch script there named Encoder Console.bat. This is the script that is run when you launch the Encoder Console from the Start menu. Right-click the batch script and choose Edit from the context menu. Windows Vista users only: Due to security restrictions you may need to right-click Notepad on your Start menu and choose "Run as administrator", then drag and drop the batch file onto the Notepad window. Once the file is open in Notepad you should see the following:

Click to enlarge

On the first line you can see that the script modifies the PATH variable by prefixing it with %CD%, a reference to the current directory (i.e. the folder the script is started in, which is the installation folder in our case). During installation we suggested that you note down the installation folder of the MKVToolnix package. If you don't know it, find it using Windows Explorer now. The default installation folder is C:\Program Files\MKVToolnix . Add the MKVToolnix path to the Encoder Console batch script as follows:

Click to enlarge

Don't forget to separate everything using semicolons. Close any open Encoder Console windows before saving your changes, then open a new Encoder Console window from the Start menu and type the following again:

MKVMerge

If everything worked, you should see MKVMerge run, although it won't do anything meaningful because we didn't pass any valid arguments. Let's do that now.

7. Writing the H.264 video bitstream into an MKV container

MKVMerge has an extensive list of arguments that can be used to write various stream types into MKV containers including many types of audio and video, and to set metadata records such as content titles and language information. The HTML documentation that is installed as part of the MKVToolnix package is more verbose than the command line help and more convenient for reading. Open it now. You'll find it on your Start menu Programs folder under MKVToolnix\Documentation\Command line reference .

As you can see, there's far too much information here for us to cover in this tutorial so we'll focus on the arguments necessary to write the video bitstream you've created into an MKV container. We'll use the global options --title <title> to set the content title and -o <outfile> to specify the name of the MKV file to write, as well as the per-track options --default-track <TID[:bool]> to mark this track as the default video track and --default-duration <TID:x> to indicate the default frame duration.

The basic syntax of MKVMerge is:

MKVMerge [global options] -o out [options1] [[options2] ...] [@optionsfile]

There are only two pieces of information we really need to complete the process. The first is the track ID (or TID). The TID refers to the track number in each input file that we want MKVMerge to import. Type the following to see the list of TID's that MKVMerge assigns to the raw H.264 bitstream:

MKVMerge -i "Sample.264"

You should see that the video stream is assigned Track ID 0. If we had multiple input files it's possible that each of them contains a track with ID 0. MKVMerge won't mix them up because the command syntax says that the options for each file always appear before the filename.

The second is frame rate of the video, i.e., the value for --default-duration. The documentation states that the value must be postfixed with s, ms, us, ns or fps to specify the default duration in seconds, milliseconds, microseconds, nanoseconds or "frames per second" respectively. The number x itself can be a floating point number or a fraction. So we could pass the frame rate, e.g. --default-duration 29.970fps, or for improved accuracy the rate/scale (inverting them to get the actual duration of a frame in seconds), e.g. --default-duration 1001/30000s.

Your command line may look something like this:

MKVMerge --title "My sample video" -o "Sample.mkv" --default-track 0:true --default-duration 0:1001/30000s "Sample.264"

You may also wish to add an audio track, e.g. an accompanying MP3 file. Audio encoding is outside the scope of this tutorial, but if you want to experiment, try a command line similar to this one:

MKVMerge --title "My sample video" -o "Sample.mkv" --default-track 0:true --default-duration 0:1001/30000s "Sample.264" --language 0:eng "Sample.mp3"

8. Playing the MKV file

You should now be able to play the MKV file using any DirectShow-based media player, e.g. Windows Media Player. Note that the first time you try to open an MKV file in later editions of Windows Media Player it will warn you that it does not recognize the file extension. Simply ignore this message by selecting the option to play the file anyway.

A more interesting way to see what's going on behind the scenes of the DirectShow media system is to use GraphStudio to render the file. GraphStudio displays the DirectShow filters that are combined to form the filter graph in order to render a file. You can examine which filters are being loaded on your system and some of the information that is being passed between them. While the graph is stopped you can also disconnect some filters and manually insert others to see the result of using alternative decoders and renderers. Here's what a typical graph might look like for an MKV file containing both video and audio:

Click to enlarge

Note that by right-clicking on the DivX H.264 Decoder Filter, you can access its property page to change various settings for decoding:

Click to enlarge

Such property pages are also common for other DirectShow filters.

Known issues for DivX H.264 Encoder Alpha 1

The following are known issues in DivX H.264 Encoder Alpha 1:

• The encoder does not provide a method to flag SAR in the bitstream. You can correct sources that are not 1:1 SAR to 1:1 using a resize transform in AVISynth. There is an example using LanczosResize in the downloadable ResoulutionSample.avs script.
  
  
• It's not possible to stop the encoder using either Ctrl+C or Ctrl+Break.
  
  
• The encoder doesn't support input from compressed AVI files. Create an AVISynth script using the AVISource filter to process such files.
  
  
• The second pass of a multipass encoding may run slowly if the target average bitrate is extremely high (e.g. approaching 20Mbps).
  
  
• The error message displayed when the width or height of the input video is not a multiple of eight pixels is incorrect.
  
  
• The components screen in the installation package refers to "Beta 1". This is a mistake.

How you can help us

We want to hear from you! Did you find our tutorial helpful? Which additional options would you like to see available in the encoder and why? Did the encoder perform well on your system? Did you find a bug? Send us your feedback.

If your feedback relates to performance issues or software stability please consider attaching some of the following to your email:

• Screenshots from CPU-Z that show your CPU, memory and mainboard configuration.
  
  
• Screenshots from DXDiag, which you can launch by simply typing DXDiag into the Run box on your Start menu, so that we can see information about your graphics card (e.g. vendor/model/memory/driver revision).
  
  
• Screenshots of any crash dialogs, including the details view if available.
  
  
• In the case of crashes, an export from MSInfo32, which you can launch by simply typing MSInfo32 into the Run box on your Start menu, so that we can see information about the operating system, running software and application errors.