Recorder Inputs

Simplifying Common Recording Workflows

In most use cases, you will likely only want to record from a game camera (or several game cameras) and/or an audio source in your scene. Instead of writing boilerplate code to extract raw pixel buffers and sample buffers from these game objects, NatCorder provides a set of helper classes which automatically handle this process. These are called Recorder Inputs.

Recording the Screen

NatCorder provides the ScreenInput recorder input for recording video frames from the screen:

// Create a recorder
var recorder = new JPGRecorder(...);
// And use the `ScreenInput` to record video frames from the screen
var screenInput = new ScreenInput(recorder);

When finishing recording, dispose the ScreenInput before stopping the recorder.

// Stop sending frames to the recorder
screenInput.Dispose();
// Finish writing
var path = await recorder.FinishWriting();

You must dispose all recorder inputs before finishing the recorder, not after.

Recording Game Cameras

NatCorder provides the CameraInput recorder input for recording one or more game cameras.

// Create a recorder
var recorder = new MP4Recorder(...);
var clock = new RealtimeClock();
// And use a `CameraInput` to record the main game camera
var cameraInput = new CameraInput(recorder, clock, Camera.main);

When finishing recording, dispose the CameraInput before stopping the recorder.

// Stop sending frames to the recorder
cameraInput.Dispose();
// Finish writing
var path = await recorder.FinishWriting();

Recording Game Audio

For recording game audio, either from a Unity AudioSource or AudioListener, NatCorder provides the AudioInput recorder input.

// Say we have an `AudioSource` we want to record
AudioSource audioSource = ...;
// Create a recorder
var recorder = new WAVRecorder(...);
var clock = new RealtimeClock();
// And use an `AudioInput` to record the audio source
var audioInput = new AudioInput(recorder, clock, audioSource);

Similarly, when finishing recording make sure to dispose the input before stopping the recorder.

// Stop sending audio frames to the recorder
audioInput.Dispose();
// Finish writing
var path = await recorder.FinishWriting();

Best Practices

There are a few things to note when recording with recorder inputs.

Recording Timestamps

Most recorders expect audio and video frames to be committed with a corresponding timestamp, specified in nanoseconds. NatCorder provides implementations of the IClock interface to simplify the process of calculating timestamps.

All recorder inputs take in a recorder and a clock. The clock is used to generate timestamps as frames are being sent to recorder by the recorder input. When recording both video and audio frames, it is highly recommended to share the same clock between your camera input and audio input. This will guarantee that frames in the recording are synchronized in time, preventing issues like drift.

Using Multiple Inputs

It is possible to use multiple recorder inputs during a single recording session. A typical use case is when recording video from a game camera along with audio from the game.

// Create a recorder
var recorder = new HEVCRecorder(...);
var clock = new RealtimeClock();
// Create recorder inputs for committing both video and audio
var cameraInput = new CameraInput(recorder, clock, mainCamera);
var audioInput = new AudioInput(recorder, clock, audioListener); 

For a given recorder, do not create multiple recorder inputs that commit the same kind of media. For example, do not create several camera inputs.

Mixed Recording

It is possible to mix manual recording with recorder inputs. The constraint, as mentioned above, is that you must use one method for video and the other for audio. Below is a typical use case that involves mixed recording:

// Start the camera preview
var cameraTexture = new WebCamTexture(...);
cameraTexture.Play();
// Create a recorder
var recorder = new MP4Recorder(...);
var clock = new RealtimeClock();
// We will manually commit video frames from the `WebCamTexture`
// But we will use a recorder input to record audio
var audioInput = new AudioInput(recorder, clock, audioListener);

With the above method, we must manually commit video frames.

while (recording)
    recorder.CommitFrame(cameraTexture.GetPixels32(), clock.timestamp);

Note that we share the same clock between our manual recording and our recorder input.

And when we're done recording, we dispose the recorder input.

// Stop sending media frames to the recorder
recording = false; // this will stop our manual recording loop above
audioInput.Dispose();
// Finish recording
var path = await recorder.FinishWriting();

Last updated