Skip to main content

Getting started

Installation​

Install the following node_modules:

npm install @overwolf/ow-electron @overwolf/ow-electron-builder @overwolf/ow-electron-packages-types

To activate the recording package, place the recorder string under \overwolf -> packages\ in your app's `package.json`:

{
  ...
  "overwolf": {
    "packages": [
      "recorder"
    ]
},
  ...
}

Recorder usage​

Import​

Add the following import statements to your app:

import { app as electronApp } from 'electron';
import { overwolf } from '@overwolf/ow-electron';

Register​

Add the following code to your app to Register to the ready state and verify that when the event is fired, the packageName is recorder.

const owElectronApp = electronApp as overwolf.OverwolfApp;
owElectronPackages.on('ready', (e, packageName) => {
    if (packageName === 'recorder') {
      console.log('Recorder package is loaded');
    }
});
recorderApi.on('recording-started', (RecordEventArgs) => {
  console.log(RecordEventArgs.filePath);
});

Use event listeners to get notified by events. For more examples see: Recording events:

Query information​

You can use the query information method to obtain the following information:

  • Display devices
  • Audio Devices
  • Supported codecs etc

Use the following snippets to query recorder information:

// obtain OBS Information
const obsInfo = await recorderApi.queryInformation();

// Get default audio encoder
console.log(obsInfo.audio.defaultEncoder);

// Get audio input devices array
console.log(obsInfo.audio.inputDevices);

// Get audio output devices array
console.log(obsInfo.audio.outputDevices);

// Get videos displays array
console.log(obsInfo.video.adapters);

// Get default video encoder
console.log(obsInfo.video.defaultEncoder);

// Get available supported video encoders
console.log(obsInfo.video.encoders);

// Get available supported audio encoders
console.log(obsInfo.audio.encoders);

Start recording​

Use the following flow to start recording in you app.

  1. Create the capture settings options object.
  2. Add capture source.
  3. Use the capture settings options object to create the settings builder. Build the capture settings using the build() method
  4. Set the recording options.
  5. Start recording.

For example:

async function startRecording(gameInfo: GameInfo = null) {
  try {
    // 1. Create the capture settings options object.
    const settingsBuilder = await recorderApi.createSettingsBuilder({
      // with default audio (mic / desktop)
      includeDefaultAudioSources: true,
    });

    /* changing default video settings
       settingsBuilder.videoSettings.fps = 60;
       settingsBuilder.videoSettings.baseWidth  = 1920;
       settingsBuilder.videoSettings.baseHeight = 1080;
     */

    // 2. Add capture source.
    if (gameInfo) {
      // game capture
      settingsBuilder.addGameSource({
        gameProcess: gameInfo.processInfo.pid, // or just 'Game.exe' name
        captureOverlays: true, // capture overlay windows
      });
    } else {
      // desktop capture
      // |monitorId| from '''queryInformation()'''
      settingsBuilder.addScreenSource({ monitorId });
    }

    // 3. Use the capture settings options object to create the settings builder. Build the capture settings using the `build()` method
    const captureSettings = settingsBuilder.build();

    const outputFolder = path.join(app.getPath('videos'), app.name);

    const fileName = game?.name ?? 'display';

    // 4. Set the recording options.
    const recordingOptions: RecordingOptions = {
      // note: if filepath already exits, it will override it.
      filePath: path.join(outputFolder, 'MyRecording'),
      autoShutdownOnGameExit: false, // when 'true' on game process exit, the recording will stop automatically
      fileFormat: 'mp4',
    };

    // 5. Start recording.
    await recorderApi.startRecording(
      recordingOptions,
      captureSettings,
      (stopResult) => {
        // also can be handled at 'recording-stopped'
        console.log('Recording stopped ', stopResult);
      },
    );

    // Start replays also here...
  } catch (err) {
    console.log('Error while starting recording', err);
  }
}

Stop recording​

Before attempting to stop the capture, use the isActive() method to verify if the capture is active. If the recording is active, use the stopRecording() method and include the optional callback to obtain details about the stopped capture. For example:

async function stopRecording() {
  try {
    const active = await recorderApi.isActive();
    if (!active) {
      return;
    }

    // stop recording
    await recorderApi.stopRecording((recordStopEventArgs) => {
      console.log(recordStopEventArgs.duration);
    });
  } catch (err) {
    console.log('Error while stopping recording', err);
  }
}

Change capture sources​

Use the settingsBuilder object to select specific capture sources. See the following examples:

Add a game source:​

const settingsBuilder = await recorderApi.createSettingsBuilder(
  captureSettingsOptions,
);
const gameProcessId = 45623; // example process Id, Obtain process Id by registering to game listeners.

// sets the game with process id 45623 to be the source of the recording.
settingsBuilder.addGameSource({ gameProcess: gameProcessId });

// Build the capture settings using the `build()` **method**
const captureSettings = settingsBuilder.build();

Add a display source:​

const settingsBuilder = await recorderApi.createSettingsBuilder();
// Example display Id, Obtain machine displays by using the queryInformation() method
const displayAltId = 'my_display_id';

// Sets the display id to be the source of the recording.
settingsBuilder.addScreenSource({ monitorId: displayAltId });

// Build the capture settings using the `build()` **method**
const captureSettings = settingsBuilder.build();

Add an audio source (default audio source):​

const settingsBuilder = await recorderApi.createSettingsBuilder(
 includeDefaultAudioSources: false,
);

// Sets the Default output audio device as the audio source for the recording,
// for example speakers or headphones.
// Any sound coming from this device will be recorded.
settingsBuilder.addAudioDefaultCapture('output');

// Alternatively you can use the default input device, like a microphone.
// settingsBuilder.addAudioDefaultCapture('input')

// Alternatively set other device ( Obtain devices from queryInformation() method)
// settingsBuilder.addAudioCapture({id: the_device_id, name: "my device"})

// Build the capture settings using the `build()` **method**
const captureSettings = settingsBuilder.build();

Replays and capture​

Start replay​

Use the following flow to start a replay:

  1. Create the capture settings options object.
  2. Use the capture settings options object to create the settings builder.
  3. Build the capture settings using the build() method
  4. Set the replays options
  5. Start Replays

For example:

async function startReplays() {}
    try {
      // Create the capture settings options object.
      const captureSettingsOptions: CaptureSettingsOptions = {
        includeDefaultAudioSources: true,
      }
      // Build the capture settings using the build() method
      const settings =
        await recorderApi.createSettingsBuilder(captureSettingsOptions);

      // set key frame every 1 second for more accurate stop timestamp;
      // note: this require more resource from the recording engine
      // settings.videoEncoderSettings.keyint_sec = 1;

      const settingsCapture = settings.build();

      const outputFolder = path.join(app.getPath('videos'), app.name, 'replays');
      // Set the replays options
      const replaysOptions: ReplayOptions = {
         bufferSecond: 30,
         rootFolder: outputFolder
         fileFormat: 'mp4',
      }

      // Start replays
      await recorderApi.startReplays(
        replaysOptions,
        // if recording (i.e start recording) is already on, settingsCapture is not mandatory
        settingsCapture,
      );

    } catch (err) {
      console.error('START replay ERROR', err);
    }

Start capturing replays​

Use the following flow to start capturing a replay:

  1. Create the replay capture options object.
  2. Use the replay capture options to start the capture replay.
  3. Use the captureReplay method to control the capturing replay.
  4. Once the captureReplay callback is returned, set the activeReplay as undefined to indicate that the replay capture is done.
async function startCaptureReplay() {
  try {
    const fileName = `MyReplay-${timestemp()}`; // probely
    // Create the replay Capture Options object.
    const replayCaptureOptions: CaptureReplayOptions = {
      fileName: 'replay-capture',
      pastDuration: 30000,
      // timeout: 10000 // stop the replay in 10 second
    };

    // Use the replay capture options to start the capture replay.
    // The captureReplay method returns the activeReplay,
    // we can use it to control the capturing
    const activeReplay = await recorderApi.captureReplay(
      replayCaptureOptions,
      (video) => {
        console.log('replay video ready ', video);
        // Once the captureReplay callback is returned we set the activeReplay
        // as undefined to indicate that the replay capture is done.
        activeReplay = undefined;
      },
    );
  } catch (error) {
    console.error('Error starting capture replay', error);
  }
}

Extend the capture replay​

Extend the captured replay's timeout while its still running by using the activeReplay object. For example:

// Check activeReplay is not undefined, which means the capture replay is currently recording.
if (!activeReplay) {
  return;
}

// Obtain how long remains in ms until the timeout, and the capture is stopped.
console.log(activeReplay.timeout);

// Stop capture replay after 10000ms
activeReplay.stopAfter(10000);

Stop the capture replay​

// Stop capture replay immediately
activeReplay.stop();