Installing videoIO on Windows

videoIO is a library written by Gerald Dalley designed to allow easy and efficient reading and writing of video files in Matlab on Windows and Linux. It is designed to enhance and/or complement other options that are available as of February 2008.

This file describes how to set up the videoIO toolbox on a 32-bit or 64-bit Windows platform. See README.txt for a more general description of this library and tips on using it.   See INSTALL.ffmpeg.txt for GNU/Linux installation instructions.

If you are (a) using Windows XP, Windows Server 2003, or Windows Vista, (b) using Matlab 2007a or later, and (c) have downloaded a videoIO package that already includes prepackaged binary .mex* files, you may skip to the Matlab Path section.  If you experience any problems running the basic tests or if you wish to build the library from its source, read this whole document.  You must download the full videoIO package to build the library from source.  If you downloaded a .zip file with "Bin" in its name, you have the wrong .zip file.

Javascript appears to be disabled in your browser. If you use a Javascript-enabled browser and enable Javascript, this document will auto-adjust to the machine configuration you specify.

Contents

Prerequisites Overview

Quick: at least skim all of this section. Select appropriate radio buttons to simplify the rest of the document.
Reminder: if you downloaded a package with "windowsBin" in its name, skip to the Matlab Path section.  To rebuild videoIO, you must download a "source" package or check out the subversion respository.
This installation procedure has been tested with a number of different configurations. All supported combinations are given below. To remove steps that do not apply to your computer, select the closest matches to your system.

Knowledge

We assume you have at least a passing familiarity with compiling C/C++ programs and that you know what environment variables are (or can follow directions exactly).

Operating System

Windows XP Pro 32-bit
Windows XP Pro 64-bit (untested)
Windows Vista 32-bit (untested)
Windows Vista 64-bit
Show all
You will probably need administrative privileges to install the 3rd party libraries.

The videoIO toolbox should work without modification on any version of Vista, on 64-bit XP Pro, and on any version of Windows Server 2003. It should work with Win2k+, maybe even Win95. To try it out, you'll need to modify the WINVER macro in a few source files.

If you use 64-bit Windows and 64-bit Matlab, you can only use 64-bit codecs. If you use 32-bit Matlab (on either 32-bit or 64-bit Windows), you can only use 32-bit codecs.

We assume the user has already installed the desired operating system.

Matlab

32-bit Matlab (R2006a or later)
64-bit Matlab (R2006a or later)
Show all
videoIO should work on Matlab 6.5 or later, but it has not been tested.

Reminder: If you use 64-bit Matlab, you can only use 64-bit codecs (and 32-bit Matlab can only use 32-bit codecs).

We assume the user has already installed Matlab.

Compiler

Microsoft Visual Studio 2003
Microsoft Visual Studio 2005
Microsoft Visual Studio 2008
      (untested)
Show all
videoIO may work on Visual Studio 6. It will probably not work with even older versions. Let us know if you get it to work with an older version or if you get it to work with the Express editions.

Visual Studio 2003 has not been tested for 64-bit builds.

Installation and configuration instructions are given below.

SDKs from Microsoft

  • Microsoft Windows SDK
    (for Vista only)
  • Microsoft Windows Server
    2003 R2 Platform SDK
    (for XP and 2003 only)
  • Microsoft DirectX SDK

If you are using Vista, you need the "Windows SDK", not the "Platform SDK". XP and Server 2003 need the Platform SDK instead.

Make sure you use the latest version of the Platform SDK (R2 as of February 2008). Older versions require manually fixing some compiler incompatibilities in Microsoft's source code.

These SDKs provide important libraries for communicating with DirectShow. Detailed installation instructions are given below.

Installation instructions for the Platform SDK, the Windows SDK, and the DirectX SDK are given below.

Codecs and Other DirectShow Components

  • Windows Media 9 codec
  • An MPEG4 codec such as:
    • DivX,
    • XviD,
    • 3ivx, or
    • ffdshow
  • An H264-compatible codec such as:
    • x264 (writing only),
    • ffdshow (reading and writing), or
    • CoreAVC Professional
  • Haali Media Splitter

DirectShow provides a platform for encoders and decoders (codecs). To encode or decode a particular video file, one must have the appropriate codec installed. Given a compression ratio, modern MPEG4 and H264 codecs can be fast and produce much higher quality results relative to older codecs. The Windows Media 9 codec family is a set of codecs that are proprietary Microsoft adaptations of MPEG4 and H264.

Use Windows Update to obtain the most recent version of Windows Media Player. The Windows Media 9 (wmv3) codec will installed automatically. This codec is needed for some tests, but otherwise is not necessary for using the library.

Like Windows Media 9, the MPEG4 and H264 codecs are not strictly necessary, but some tests will softly fail if they are not installed.  Here are some places to go for fully legal codecs (as of February 2008):

Note that ffdshow-tryout actually supplies a very large set of codecs (including Windows Media 9, MPEG4, H264, and others) with intelligent encoding defaults.  This is especially useful on 64-bit platforms since there are few other 64-bit codecs available (as of February 2008).

If you wish to decode videos in non-AVI containers (e.g. .mp4, .ts, .mts, .m2ts, .mkv, .ogg, etc.), consider installing the Haali Media Splitter as well.  If you will be working with 24pf AVCHD or MPEG2 videos, you may wish to read our pulldown removal document after installing videoIO.  As of April 2008, the Haali splitter is only available for 32-bit applications.

Environment Variables

Quick: carefully follow all of these instructions.

If you do not know what environment variables are or how to permanently change them in Windows, see FAQ.txt.

In the instructions below,

Alternatively, return to the prerequisites section of this document and select the configuration options you'll be using. If you use an HTML4-compatible browser with JavaScript enabled, this document will self-customize to your configuration.

In these instructions, some directories will need to be added to various environment variables. Many of these folders will not exist until later in the instructions; however, we will modify all of the environment variables now. This makes the installation process faster and less complex.

INCLUDE

Create the "INCLUDE" system environment variable (if it does not already exist) and add the following paths to it.

C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Samples\Multimedia\DirectShow\BaseClasses
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include
C:\Program Files\Microsoft SDKs\Windows\v6.1\Samples\Multimedia\DirectShow\BaseClasses
C:\Program Files\Microsoft SDKs\Windows\v6.1\Include
%DXSDK_DIR%\Include

When using path-like environment variables on Windows, place a semicolon between each string. For example, if the current INCLUDE variable is "C:\foo" and you wish to add "C:\bar\baz", the new INCLUDE variable will be "C:\foo;C:\bar\baz" (without quotes). It is important to have no extra spaces before or after the semicolons. We have placed each path on a separate line in this document for readability purposes.

Note: On Windows XP, install the Platform SDK, even though the name might seem to suggest it requires Server 2003. The listed Platform SDK is the correct one for Windows 2000, Windows Server 2003, Windows XP 64-bit, Windows XP Pro, and Windows XP SP1.

Note: DXSDK_DIR is an environment variable which will be created when the DirectX SDK is installed.

It's important that the include directories be in the order given above (i.e. the BaseClasses directory must appear before the base SDK's Include, and that before the DirectX's Include). Microsoft likes to create stub headers (.h files) with the same names as the real ones and if the stubs are found first, they break the compilation.

LIB32

Add the following strings to the "LIB32" system environment variable (you may skip this if you are using 64-bit Matlab only):

C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Samples\Multimedia\DirectShow\BaseClasses\WIN2000_RETAIL
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib
C:\Program Files\Microsoft SDKs\Windows\v6.1\Samples\Multimedia\DirectShow\BaseClasses\Release
C:\Program Files\Microsoft SDKs\Windows\v6.1\Lib\x86
C:\Program Files\Microsoft SDKs\Windows\v6.1\Lib

Order is important here too.

LIB64

Add the following strings to the "LIB64" system environment variable (you may skip this if you are using 32-bit Windows):

C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Samples\Multimedia\DirectShow\BaseClasses\WIN2000_RETAIL
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib
C:\Program Files\Microsoft SDKs\Windows\v6.1\Samples\Multimedia\DirectShow\BaseClasses\x64\Release
C:\Program Files\Microsoft SDKs\Windows\v6.1\Lib\x64
C:\Program Files\Microsoft SDKs\Windows\v6.1\Lib

Order is important here too.

Add the appropriate one of the following strings to the "PATH" system environment variable (remember to omit " (x86)" if you are using 32-bit Windows).

C:\Program Files (x86)\Microsoft Visual Studio 7\VC\bin
C:\Program Files (x86)\Microsoft Visual Studio 8\VC\bin
C:\Program Files (x86)\Microsoft Visual Studio 9\VC\bin

Operating System Updates

Quick: Windows Vista users must manually install an OS patch.
Windows Vista unfortunately shipped with a buggy version of a critical function used to create new AVI files. If you are using Vista and wish to create videos, you must manually download and install Microsoft's KB939130 patch.

As of Oct. 2007, this patch must be manually downloaded and installed. It is not pushed through Windows Update. When service pack 1 is released, this (or an equivalent patch) is expected to be included.

As far as the authors know, all versions of XP work with this software, though we naturally recommend that users regularly update their system using Windows Update to avoid security risks.

Visual Studio

Quick: Carefully follow all these instructions, even if you have already installed Visual Studio.
If you want to rebuild the mex binaries, you need a compiler. The Windows-specific portions of this library were written primarily using Visual Studio 2005. Since we do not make extensive use of templates and other advanced C++ features in this library, it should work on older versions of Visual Studio, perhaps as far back as version 6. We have not attempted to use Visual Studio Express.

First, install Visual Studio:

  1. Purchase Visual Studio
  2. Use user an account with administrative privileges
  3. Start the installer; if you want to compile 64-bit versions, when choosing the custom installation options, check
    Microsoft Visual Studio 2005 Professional → Language Tools → Visual C++ → X64 Compilers and Tools
    You may uncheck all .NET and all non C++ options if you want to save space and installation time. If you get an Vista incompatibility warning, ignore it and tell Vista to run the program anyway.
If using Visual Studio 2005, download and install Visual Studio 2005 Service Pack 1 if you have not already done so via Windows Update or via direct download. Installation may take many hours. Even though you may be tempted to skip the service pack installation, install it anyway, especially if you're using a single-core, single-processor machine. Without the service pack, Visual Studio has a tendancy to hang for literally minutes at a time.

Now, we get to configure Visual Studio so it can find the SDKs we'll be installing. As was the case with the environment variables, it's easier to do it all at the same time, so we'll do it now. In Visual Studio, go to

Tools → Options... → Projects and Solutions → VC++ Directories
then
  1. Select "Win32" in the Platform pulldown
    1. In "Include files", add the following, without quotes: "$(INCLUDE)"
    2. In "Library files", add the following, without quotes: "$(LIB32)"
  2. Select "x64" in the Platform pulldown (you may skip this step if you are using 32-bit Windows or are only using 32-bit Matlab)
    1. In "Include files", add the following, without quotes: "$(INCLUDE)"
    2. In "Library files", add the following, without quotes: "$(LIB64)"

Windows SDK

Quick: If you are using Windows XP or Windows Server 2003, skip this step.
"The Windows SDK includes documentation, samples, and tools designed to help you develop Windows applications and libraries using both Win32(R) and .NET Framework ... technologies targeting Windows Vista," (Microsoft).
  1. Download the SDK. As of Sept. 2008, version 6.1 was the current version. Future versions may require changing these instructions.
  2. Do a custom installation and check any options that have "x86" or "x64" in them, unless you know you will not want to compile the library in 32-bit or 64-bit mode, respectively. You can uncheck any .NET options if you don't intend to use .NET (this library doesn't).
  3. Launch Visual Studio and load
    C:\Program Files\Microsoft SDKs\Windows\v6.1\Samples\Multimedia\DirectShow\BaseClasses\baseclasses.sln
    Then using the menus,
    1. Build → Configuration Manager... →
      1. Pull down the "Active solution platform:" selector and look for "x64".
      2. If it's already there, stop and jump to the batch build step below. Otherwise, select "<New...>".
      3. In "Type or select the new platform:", select "x64".
    2. Project → Base Classes Properties... → Configuration Properties → C/C++ → Language →
      1. Pull down the "Configurations:" selector and pick "All Configurations".
      2. Pull down the "Platform:" selector and pick "All Platforms".
      3. Change the "Treat wchar_t as Built-in Type" to "No (/Zc:wchar_t-)".   Matlab was built with this option, so mex files and so must anything they link to (including the library we're creating here).
    3. Build → Batch Build... →
      1. Unless you know you will only be using some versions, select and build all of the configurations.

Platform SDK

Quick: If you are using Windows Vista, skip this step. If you are using XP or Windows Server 2003, follow the instructions.
"The Platform SDK for Microsoft(R) Windows Server(R) 2003 R2 contains the information and tools you need to develop Windows-based applications. You can use this SDK to develop both 32- and 64-bit applications," (Microsoft).
  1. Download the SDK. As of February 2008, R2 was the current version and it contains important changes relative to R1 and earlier versions of the Platform SDK. Unfortunately, most search engines (including Microsoft's) return a pre-R2 release as the first result. Make sure you use R2 or later.
  2. Do a standard install. If you would like 64-bit support, check any options that have "x64" in them.
  3. Edit "C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Samples\Multimedia\DirectShow\BaseClasses\makefile" and add
    cflags=$(cflags) /Zc:wchar_t-
    as a new line after the !include <win32.mak> line. This forces the same character data type definitions that Matlab requires.
  4. Run the following commands from the command prompt (Start → Run... → type in "cmd.exe" without quotes):
    set PATH="%PATH%;C:\Program Files\Microsoft Visual Studio 8\VC\bin"
    cd "C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Samples\Multimedia\DirectShow\BaseClasses"
    "C:\Program Files\Microsoft Visual Studio 8\VC\vcvarsall.bat"
    set LIB=%LIB%;%LIB32%
    nmake NODEBUG=1 _CRT_SECURE_NO_DEPRECATE=1

    If you are using a version of Visual Studio other than 2005 and/or if you are using a 64-bit operating system, adjust the aboves paths as appropriate.

    If you're building 64-bit versions, you will most likely need to add "amd64" as a command-line argument to "vcvarsall.bat" and change "set LIB=%LIB%;%LIB32%" to "set LIB=%LIB%;%LIB64%". This is untested.

    If you are using Visual Studio 2003, use vcvars32.bat instead of vcvarsall.bat.

DirectX SDK

Quick: Download and install the DirectX SDK and tell Visual Studio where the include and library files are.
DirectX is a collection of multimedia APIs by Microsoft. In order to read and write a wide array of video files on Windows, we need to use DirectShow. Some of the files required for using DirectShow are found in the DirectX SDK.
  1. Download the latest DirectX SDK. Microsoft has historically released new versions every 3-6 months. As of Sept. 2008, this download was nearly a half a gigabyte.
  2. Install the SDK. The default options are fine.
  3. See if the DXSDK_DIR system environment variable was created (see the FAQ.txt for instructions on viewing and modifying environment variables). If it was not created by the installer, set DXSDK_DIR to
    C:\Program Files (x86)\Microsoft DirectX SDK (August 2008)
    (modify this directory to point to your SDK's base directory).

Building the Library

Quick: Follow all of these instructions.
We're now finally ready to build the library using Matlab.
  1. Start a new Matlab session. You must relaunch Matlab so that it can see the new values of the environment variables you have created and/or modified. Any time you modify environment variables used by Matlab (or programs it calls), you must completely exit Matlab and restart it.
  2. In Matlab, run the following if you have not already done so:
    mex -setup
    Follow the on-screen instructions. If you have multiple compilers installed, choose the one that was configured in the Visual Studio section of this document.
  3. Edit the file
    %APPDATA%\MathWorks\MATLAB\R2007b\mexopts.bat
    replacing "R2007b" with your Matlab revision.
  4. In Matlab, go to the directory where you've placed the videoIO source files and run
    buildVideoIO
    If the build fails, recheck that you followed all of the previous instructions in this file exactly. You may also want to look at the FAQ for solutions to common problems.

Matlab Path

Quick: add the installation directory to the Matlab path
In Matlab add the base installation directory (but not all subdirectories) to the path. In the GUI this can be done by
File → Set Path... → Add Folder...
Alternatively, from the Matlab command line this can be done using the "addpath" and "savepath" functions.

Do not add directories recursively: the @videoReader/, @videoWriter/, and private/ directories are handled automatically by Matlab's object system. The tests/ subdirectory contains files that are essentially private (e.g. a function named testAll could easily appear in other toolboxes or in the user's own code).

Testing

Quick: test the library

In Matlab, go to the tests/ subdirectory and run testAll:

% if this fails, you forgot to add the videoIO directory to your matlab path.
cd(fullfile(videoIODir, 'tests')); 

% This will take a long time (perhaps up to a few hours) to complete, but the 
% most basic and most critical tests are run first.  
testAll 

Usage

Quick: here are some pointers to getting started using the library
See README.txt for a simple usage example. For user-level documentation, type any or all of the following at the Matlab prompt:

help buildVideoIO
help videoReader
help videoWriter
help videoread

Also consider looking at tests/videoWriterDemo.m and tests/addFrameDemo.m for examples of writing videos.