File: README — Documentation for wiretap (0.1)

Ruby bindings for Autodesk Wiretap

These bindings allow you to access Wiretap-enabled Autodesk Media&Entertainment systems such as Flame, Flint and Smoke. To use the bindings with your Media system you will need the following:

Wire license
Wiretap daemon (should be installed and started separately on the machine to which the Stone storage devices are connected)

Dependencies for clip output

The bindings depend on the Wiretap SDK and ActiveSupport (available as part of Rails).

It is possible to export video frames as .sgi images without any dependencies (clips will be exported as image sequences).

However, if you need to export or import video or export and import audio you will need to have additional libraries and binaries installed. These are used by the bindings to de/encode the graphics and sound.

For video files:

mencoder + ffmpeg

For sound files:

libsndfile

Running the unit tests

Define a RUBY_WIRETAP_TEST_HOST environment variable that will contain the hostname or IP address of your IFFS system. Make a PAL 720x576 8-bit project on the system and name it “RubyWiretapTest”.

Run rake.

Building the bindings

To build the bindings you will need the Wiretap SDK, distributed free of charge by Autodesk. Currently you also need to use GCC 3.3 to compile against the supplied libraries (GCC 4.0 will not work with current stable libraries, but it is required to build against new beta version).

Please note that it’s currently not possible to build the bindings on a Windows system. If You require to build them on Windows, contact authors. Supported build systems are Linux, MacOS (PowerPC only with current stable libraries) and IRIX (although this configuration has not been tested yet).

Additionally, Wiretap SDK will only run and link in Rosetta on Intel Macs (therefore your Ruby will also need to be PPC). (or You can try to use new beta version on Wiretap SDK)

Build the bindings by issuing the following commands:

export WIRETAP_INSTALL_DIR=/usr/local/lib/wiretap
rake build

Simplistic examples

Test a Wiretap connection:

require 'lib/wiretap'
server = Wiretap::Server.new("flame-01")
puts "Flame is running" if server.alive?

Retrieve frame 22 from a clip as an SGI file:

require 'lib/wiretap'
clip = Wiretap::open('192.168.2.2/stonefs/SuperCommercial/Default/capture')
raise "It has to be a clip" unless clip.clip?
clip.frames.dump(22, '/tmp/frame22.sgi')

See the documentation for more info on accessing Wiretap servers and nodes from your Ruby program.

Sound and image output

The bindings support decoding and encoding of all clip formats on Discreet framestores, inlcuding 8, 10 and 12bit video and standard 48khz audio. Both 12-bit packed (36bit per pixel) and 12-bit unpacked (48bit per pixel) variants are supported. Please note that when 10 or 12 bit video is extracted it’s going to be upsampled to 16bit per channel as supported by .sgi image format. There are no formats that natively support 10bit or 12bit color (except for Cineon and DPX which are outside of the scope this extension).

Sound is exported as AIFF files.

Test footage

The test footage used for the bindings is courtesy of HecticElectric BV, Amsterdam. The use of these clips for testing the bindings has been explicitly and exclusively allowed for this product only. You are not allowed to distribute or use the footage separately from the bindings or for purposes other than testing the software.

Testing procedures

On your Flame, Flint or Inferno system, create a new project on the framestore called “RubyWiretapTest”. Make sure that it’s 8-bit PAL 720x576 and that it has a “Default” library (it gets created for you automatically).

If you are using Smoke, Fire, Backdraft or Backdraft Conform as Wiretap host and you want to test the bindings on it, you will need to have a top-level library called “RubyWiretapTest” and a project inside it called “Default”.

Then define the environment variable referring to your system and run the test suite:

export RUBY_WIRETAP_TEST_HOST=address_of_your_flame_system
rake

During the test run the program will write frames and sound to this library. Authors hold no responsibility if other clips or materials on the framestore get lost or damaged during the operation.

After that the media has been written to the framestore (which tests the write operations) the same media is going to be retrieved. If the dependencies are met, the images are going to be converted and output to the test directory - you will receive a number of graphics files and a sound file. Please analyze the output carefully to make sure clip output is working as advertized.