Skip to main content

overwolf.media.replays API

Use this API to capture a short video replay of the currently running game.

info

Please check the replay API sample app that demonstrates a primary usage in the API. Please read all the info about video capture usage and options on our video capture best practices guide.

Methods Reference

Events Reference

Types Reference

Sample app

In our APIs sample apps repository, you can find and download two sample apps that demonstrate the usage in the replays API:

  • The replay-manual Sample App. Demonstrates how to use a manual capture using the replay API.
  • The replay-auto-highlight Sample App. Demonstrates how to use the auto-highlights mode using the replay API.

It's a great place to get started - All the samples in this repository are built with JS code and demonstrate primary usage in the API.

Functionality

The sample app's functionality is pretty straightforward: You launch it, open the dev console (to see all the debug messages), and hit the Turn On button to start the capture and Turn Off to stop it. In addition, you have the Get State button that tells you the current state (if the capture mode is turn on or off).

You can look at the dev console to see the status of each call (success, failure, etc.). Once done, you can hit the open media folder to check the captured clip.

Besides the above, you have several minor differences between the manual app and the auto-highlights app:

replay-manual-sample

After hitting the "turn on" button, you have to manually click the "capture" button. That will initiate a short clip capture.

replay-auto-highlights-sample

In this sample app, you only have to click on the "turn on" button to initiate the auto-capture mode. Once the app recognizes supported auto highlight in the game (kill, death, etc.), it will auto-capture it. So no need to click on a "capture" button like in the manual capture app.

Note - if the current game does not support auto-highlights, the sample app will not work and display an error message.

Setting up

Download the app's source code from the repository as a zip file, and extract it to a new folder on your machine.
Load the app as an "unpacked extension" (Note that to do that you have to whitelist your OW username as a developer).

  • Open the Overwolf desktop client settings (by right-clicking the client and selecting "Packages" Or by clicking on the wrench icon in the dock and going to the "About" tab => "Development Options").
  • Click on "Development options".
  • In the opened window, click on "Load unpacked extension" and select the extracted replay-manual-sample folder. This will add the manual sample app to your Overwolf dock. Do the same with the replay-auto-highlights-sample to install the auto-highlights sample app.
  • Make sure you are logged in to the OW client. Otherwise, you will get an "Unauthorized App" error message. (Click on the "Appstore" icon in the OW dock to login to the OW client).
  • Click on the app's icons in your OW dock to run the apps.

turnOn(parameters, callback)

Version added: 0.130

Turns on background replay capturing. Without calling it first, you will not be able to create video replays.

Only apps that have the VideoCaptureSettings permission in the manifest are considered as a capture app and displayed in the OW client capture tab.

tip

Using this method you can quickly get the game highlights videos without the overhead of using both OW events and streaming API’s.

There’s no need to know/understand each supported game’s mechanics, game flow, edge cases, timings, etc.
Just request for any supported game highlight and OW will provide you with a video file that includes this event.

ParameterTypeDescription
parametersReplaySetting objectContainer for the capture configuration
callback(Result: TurnOnResult) => voidA callback function which will be called with the status of the request

Important notes

  • turnOn() will fail if highlights are requested but not supported for the current game.
    To get the list of supported highlights call getHighlightsFeatures().
  • The below call will override your current OW client settings only if video setting is not null or values are different than zero.
  • For each OW app that uses this feature, a new video folder will be created. So in theory, a few OW installed apps can capture the same highlight, from the same game (if all these apps set to capture this highlight from this game of course).

Usage Example

 let streamSetting = {
"video": {
"sub_folder_name": folderName,
"buffer_length": bufferLength,
"base_frame_size_source" : ["Setting","Auto"] , // if not set, "Setting" is the default
"frame_size_method": ["Original", "ExactOrKeepRatio", "ExactOrClosestResolution"] , // // Original
"override_overwolf_setting" : false,
"fps" :30,
"width" :1920,
"height" : 1080
},
"quota": {
"max_quota_gb": 2,
"excluded_directories": [ "cool_session" ] //set directories that are not part of the quota
}
};

overwolf.media.replays.turnOn({
"settings": streamSetting,
"highlights": {
"enable" : true, //set false if you want to record the highligths manually
"requiredHighlights" : ["death","assist","victory"] // events to capture
}
}, callback);

turnOff(callback)

Version added: 0.117

Turns off background replay capturing. Call this as soon as you’re no longer interested in capturing, in order to free up resources.

ParameterTypeDescription
callback(Result: TurnOffResult) => voidA callback function which will be called with the status of the request

Callback argument: Success

A callback function which will be called with the status of the request

{ "status": "success" }

getState(replayType, callback)

Version added: 0.78

Returns whether replay capturing is turned on or off.

Deprecated

This function is Deprecated. Instead, please use overwolf.media.replays.getState().

ParameterTypeDescription
replayTypeReplayType enumThe type of replay to get state for
callback(Result: GetStateResult) => voidA callback function which will be called with the status of the request

getState(callback)

Version added: 0.117

Returns whether replay capturing is turned on or off.

ParameterTypeDescription
callback(Result: GetStateResult) => voidA callback function which will be called with the status of the request

Note that you get the state only from the window that turned the capturing on.

capture(replayType, pastDuration, futureDuration, captureFinishedCallback, callback)

Version added: 0.78

Starts capturing a replay to a file.

Deprecated

This function is Deprecated.

note

Capture() will automatically stop after it reaches the futureDuration. No need to call stopCapture(). If you want to stop the capture manually, you can use startCapture().

  • A replay id will be returned in the callback which is needed to finish capturing the replay.
  • You can only call this method if replay mode is on and no other replay is currently being captured to a file.
ParameterTypeDescription
replayTypeReplayType enumThe type of replay to capture
pastDurationintThe video length, in milliseconds to include prior to the time of this call (up to 600000 ms).
futureDurationintThe video length, in milliseconds to include after the time of this call. To ignore it, simply give it a non-positive value
captureFinishedCallback(Result: ReplayResult) => voidA callback function which will be called when capturing is finished, at the end of the future duration supplied to this call
callback(Result) => voidReports success or failure

capture(pastDuration, futureDuration, captureFinishedCallback, callback)

Version added: 0.78

Starts capturing a replay to a file.

note

Capture() will automatically stop after it reaches the futureDuration. No need to call stopCapture(). If you want to stop the capture manually, you can use startCapture().

  • A replay id will be returned in the callback which is needed to finish capturing the replay.
  • You can only call this method if replay mode is on and no other replay is currently being captured to a file.
ParameterTypeDescription
pastDurationintThe video length, in milliseconds to include prior to the time of this call (up to 600000 ms)
futureDurationintThe video length, in milliseconds to include after the time of this call. To ignore it, simply give it a non-positive value
captureFinishedCallback(Result: ReplayResult) => voidA callback function which will be called when capturing is finished, at the end of the future duration supplied to this call
callback(Result: StartReplayResult) => voidA callback function which will be called with the status of the request

startCapture(replayType, pastDuration, callback)

Version added: 0.78

Starts capturing a replay to a file.

Deprecated

This function is Deprecated.

note

startCapture() won't automatically stop until you call stopCapture().

It's useful if you want to stop the capturing based on a future event, like video combos: kill, doublekill, triple kill - where you can't predict what will happen after the first kill. If you want to automatically stop after it reaches futureDuration, you can use capture().

  • A replay id will be returned in the callback which is needed to finish capturing the replay.
  • You can only call this method if replay mode is on and no other replay is currently being captured to a file.
ParameterTypeDescription
replayTypeReplayType enumThe type of replay to capture
pastDurationintThe video length, in milliseconds to include prior to the time of this call
callback[(Result: FileResult)]/ow-native/reference/media/ow-media#fileresult-object) => voidA callback function which will be called with the status of the request

startCapture(pastDuration, callback)

Version added: 0.78

Starts capturing a replay to a file.

note

startCapture() won't automatically stop until you call stopCapture().

It's useful if you want to stop the capturing based on a future event, like video combos: kill, doublekill, triple kill - where you can't predict what will happen after the first kill. If you want to automatically stop after it reaches futureDuration, you can use capture().

  • A replay id will be returned in the callback (as the last part of the file name ) which is needed to finish capturing the replay.
  • You can only call this method if replay mode is on and no other replay is currently being captured to a file.
ParameterTypeDescription
replayTypeReplayType enumThe type of replay to capture
captureFinishedCallbackfunctionA callback function which will be called when capturing is finished, at the end of the future duration supplied to this call
callback[(Result: FileResult)]/ow-native/reference/media/ow-media#fileresult-object) => voidA callback function which will be called with the status of the request

stopCapture(ReplayType, replayId, callback)

Version added: 0.78

Finishes capturing a replay and returns a url to the created video file.

Deprecated

This function is Deprecated.

  • You can only call this method if replay mode is on and using a valid id of a replay being captured to a file (“url” property).
ParameterTypeDescription
replayTypeReplayType enumThe type of replay to capture
replayIdstringThe id of the replay you want to stop capturing
callback[(Result: FileResult)]/ow-native/reference/media/ow-media#fileresult-object) => voidA callback function which will be called with the status of the request

stopCapture(replayId, callback)

Version added: 0.117

Finishes capturing a replay and returns a url to the created video file.

  • You can only call this method if replay mode is on and using a valid id of a replay being captured to a file.
ParameterTypeDescription
replayIdstringThe id of the replay you want to stop capturing. Read notes.
callback(Result: ReplayResult) => voidA callback function which will be called with the status of the request

replayId notes

The replayId is returned in the callback of the startCapture(), as the last part of the file name.

getHighlightsFeatures(gameId, callback)

Version added: 0.130

Get supported auto highlights features for a game.

You can browse in our list of auto-highlights supported games.

ParameterTypeDescription
gameIdintThe id of the game you want to capture it highlights
callback(Result: GetHighlightsFeaturesResult) => voidA callback function which provides a list of the generated video highlights URL’s for this session and relevant metadata for each highlight

Usage example

//get available Fortnite highlights

overwolf.media.replays.getHighlightsFeatures(21216, JSON.stringify(console.log))

If you run getHighlightsFeatures() for unsupported game, you will get "no feature supported" error:

{
"success": false,
"status": "error",
"error": "no feature supported"}

changeVolume(audioOptions, callback)

Version added: 0.256

Changes the volume of the replay.

ParameterTypeDescription
audioOptionsStreamAudioOptions ObjectThe new volumes encapsulated in an object
callback(Result) => voidReturns with the result

onCaptureError

Version added: 0.78

Fired when an errror has occurred with the capturing, with the following structure: CaptureErrorEvent Object

onCaptureStopped

Version added: 0.117

Fired when replay service is stopped, with the following structure: CaptureStoppedEvent Object

onCaptureWarning

Version added: 0.117

Fired on capture service warning, with the following structure: CaptureWarningEvent Object

onReplayServicesStarted

Version added: 0.117

Fired when an replay service was started (on any app), with the following structure: ReplayServicesStartedEvent Object

onHighlightsCaptured

Version added: 0.130

Fired when a new Replay highlight recorded (when highlightsSetting is enabled), with the following structure: HighlightsCapturedEvent Object

Usage

overwolf.media.replays.onHighlightsCaptured.addListener(function(info) {
console.log("a stream had captured: " + JSON.stringify(info));
});

HighlightsCapturedEvent Object

ParameterTypeDescription
game_idnumber
match_idstring
match_internal_idstring
session_idstring
session_start_timenumber
match_start_timenumber
start_timenumber
durationstring
eventsstring[]
raw_eventsraw_events[]
media_urlstring
media_pathstring
media_path_encodedstring
thumbnail_urlstring
thumbnail_encoded_pathstring
replay_video_start_timenumber

Event data example

{
"game_id":5426,
"match_id":"2334906612",
"match_internal_id":"0b818d3e-99a0-4e93-9bdd-b2af596bfc50",
"session_id":"f05099982b6c452dbf0ba8250d766dc8",
"session_start_time":1576572688739,
"match_start_time":1576572691238,
"start_time":1576572986453,
"duration":19333,
"events":["victory"],
"raw_events":[{"type":"victory","time":10000}],
"media_url":"overwolf://media/replays/Game+Summary/League+of+Legends/League+of+Legends_17-12-2019_10-51-31-222/League+of+Legends+12-17-2019+10-56-36-455.mp4","media_path":"C:\\Users\\Er\\Videos\\Overwolf\\Game Summary\\League of Legends\\League of Legends_17-12-2019_10-51-31-222\\League of Legends 12-17-2019 10-56-36-455.mp4",
"media_path_encoded":"file:///C:/Users/Er/Videos/Overwolf/Game Summary/League of Legends/League of Legends_17-12-2019_10-51-31-222/League of Legends 12-17-2019 10-56-36-455.mp4",
"thumbnail_url":"overwolf://media/thumbnails/Game+Summary/League+of+Legends/League+of+Legends_17-12-2019_10-51-31-222/League+of+Legends+12-17-2019+10-56-36-455.mp4","thumbnail_path":"C:\\Users\\Er\\Videos\\Overwolf\\Game Summary\\League of Legends\\League of Legends_17-12-2019_10-51-31-222\\Thumbnails\\League of Legends 12-17-2019 10-56-36-455.jpg",
"thumbnail_encoded_path":"file:///C:/Users/Er/Videos/Overwolf/Game Summary/League of Legends/League of Legends_17-12-2019_10-51-31-222/Thumbnails/League of Legends 12-17-2019 10-56-36-455.jpg",
"replay_video_start_time":1576572986699
}

Find all the highlights of a specific match

The match_id field from this event is equal to the pseudo_match_id from match_info. You can cross-reference these two id's in order to find all the highlights of a certain match. (you should NOT use the match_internal_id as it's an OW internal ID)

That works for all the supported games, except LOL: in LOL the match_id from onHighlightsCaptured is not equal to pseudo_match_id - it's the real RIOT match ID. So if you wanty to find the highlights of a specific LOL match, you should cross-reference this match_id with the matchId from the matchState.

raw_events Object

ParameterTypeDescription
typestring
timenumber

ReplayHighlightsSetting Object

Version added: 0.78

Container for the Auto highlights configuration.

ParameterTypeDescription
enableboolEnable auto Highlights recording
requiredHighlightsstringAn array of requested highlights. use ["*"] to register all features. You can get the list of the supported highlights using the method getHighlightsFeatures())

ReplaySetting Object

Version added: 0.133

Capture settings container.

ParameterTypeDescription
highlightsReplayHighlightsSetting ObjectOptional. Enable auto Highlights recording
settingsReplayStreamParams ObjectThe stream provider settings

Object data example

"settings": {
"video": { "buffer_length": 20000 },
"audio": {
"mic": {
"volume": 100,
"enable": true,

},
"game": {
"volume": 75,
"enable": true
}
},
"peripherals": {
"capture_mouse_cursor": "both"
},
"quota": {
"max_quota_gb": 2,
"excluded_directories": [ "cool_session" ] //set directories that are not part of the quota
}
}

ReplayStreamParams Object

Version added: 0.147

Represents the settings required to start a replay video.

NameTypeDescriptionSince
audioStreamAudioOptions ObjectStream audio options0.78
peripheralsStreamPeripheralsCaptureOptions ObjectDefines how peripherals (i.e. mouse cursor) are streamed.
Permissions required: DesktopStreaming
0.78
max_quota_gbdoubleMax media folder size in GB.
deprecated
0.78
quotaStreamQuotaParams objectParameters for limiting disk space allocation. See note0.147
videoReplayVideoOptions ObjectReplay video options0.147
ignore_session_folderboolDefines whether or not to use the session folder naming for replays.
Defaults to false (session folder naming will be used).
0.254
capture_desktopStreamDesktopCaptureOptions ObjectDefines the desktop streaming options.0.254

quota note

You can allocate limited disk space for your captured video and even set an array of directories that are excluded from max quota calculations.
You can use it, for example, to implement "favorites captures" feature: allow your app's users to mark some captured videos as "favorites," move them to one of the excluded directories, and make sure that they not deleted when the quota has reached the limit. Of course, this is just a suggested usage example.

ReplayVideoOptions Object

Version added: 0.147

Replay video options.

NameTypeDescriptionSince
auto_detectboolDefines if to try to automatically detect the best settings for streaming0.83
auto_calc_kbpsboolDefines if to try to automatically calculate the kbps. If set to true, then the max_kbps field is ignored0.83
fpsintDefines the Frames Per Second for the stream0.78
widthintDefines the stream width in pixels0.78
heightintDefines the stream height in pixels0.78
max_kbpsintDefines the maximum KB per second of the stream. See notes.0.78
buffer_lengthintDefines the length of the buffer to be recorded in millisenconds (max 40 seconds)0.83
encoderStreamingVideoEncoderSettings ObjectDefines the video encoder settings to use0.83
capture_desktopStreamDesktopCaptureOptions ObjectDefines the desktop streaming options.
Permissions required: DesktopStreaming
0.83
test_drop_frames_intervaluintThe interval, in milliseconds, in which to test for dropped frames0.92
notify_dropped_frames_ratiodoubleThe ratio of dropped to non-dropped frames for which to issue a notification0.92
sub_folder_namestringDefines Sub folder for video file path destination (See note below this table)0.103
override_overwolf_settingboolDo not use Overwolf capture setting.0.103
max_file_size_bytesuintDefines file maximum size. when video reach {max_file_size_bytes}, the recorder will flush the video file and stat a new video file.0.103
include_full_size_videoboolin case max_file_size_bytes is onfull video will be recorded to disk parallel to splits videos.0.105
disable_when_sht_not_supportedboolDo not start video replay service in case shared texture is not supported.0.105
indication_positionindication_position EnumPosition of the recorder indicator. Available for video capture only.0.143
indication_typeindication_type EnumType of the recorder indicator. Available for video capture only.0.143
use_app_display_nameboolUse the app display (if has any e.g dock_button_title name when creating video folder. See note0.154
sourcesVideoSource[]Add sources to video. See note0.159
base_frame_size_sourceeVideoBaseFrameSizeSource EnumSee note0.168
frame_size_methodeVideoFrameSizeCalcMethod EnumSee note0.168
game_window_captureGameWindowCapture ObjectDedicate option for game window capture (when available). See note0.176
keep_game_capture_on_lost_focusboolKeep capturing the game when the game loses focus (i.e do not show "Be Right Back"). Note: if game is minimized, BRB will be shown.0.180
color_spacestring | overwolf.streaming.enums.VideoColorSpecThe default value is: Rec709.0.254
color_formatstring | overwolf.streaming.enums.VideoColorFormatThe default value is: NV12.0.254
fragmented_video_fileboolSplits the video to smaller fragments which allows for the immediate start of video playback after downloading only a small initial segment.
Defaults to false.
0.254

base_frame_size_source notes

Possible values:

  • If not set, "Setting" (setting configuration) is the default. This means that it will look at what method has been selected in the eVideoFrameSizeCalcMethod field.
  • "Auto" is logical width\height (if in-game, take the game, otherwise take monitor).

frame_size_method notes

If the above base_frame_size_source was set as "Setting", the bellow values are available:

  • "Original": Original calculation to get the output resolution for the needed quality keeping the aspect ratio.
  • "ExactOrKeepRatio": Get the exact resolution from a resolutions list for the needed quality; if not found in the list, then calculate a new resolution keeping the aspect ratio.
  • "ExactOrClosestResolution": Find the closer resolution from a resolutions list for the needed quality.

GameWindowCapture Object

Version added: 0.176

Game window capture options.

NameTypeDescriptionSince
enable_when_availableboolDisabled by default0.176
capture_overwolf_windowsboolDefault value is taken from the Overwolf Settings0.176

game_window_capture notes

Dedicate option for specific games (CSGO, Warzone, Destiny 2) that requires exclusive mode to interact with the OW windows.

Up until now when we recorded these games in windowed mode, it resulted in a recording of the whole desktop.
We now provide the option to record only the game window. This feature is disabled by default, but you can enable it with these recording settings properties:

"video": {
"game_window_capture": {
"enable_when_available": bool, // Disabled by default
"capture_overwolf_windows": bool // Default value is taken from the Overwolf Settings
}
}

Note that we added a new is_game_window_capture property to onReplayServicesStarted event to inform the app Creator if this new capturing feature was used or not on the current OW window.

sources notes

Using the "sources," you can add a video source (currently, only Webcam is supported) to the captured video.
Read about overwolf.media.replaysVideoSource for more info.
Note: This API does support secondary files for Webcam (means, the webcam rendered to a different video file), while the overwolf.streaming API does not.

use_app_display_name notes

If this flag in on, when creating a video capture folder, it will use the app "short name" as the folder name, instead of using the app name from the manifest.
The app "short name" is defined in the dock_button_title manifest flag.

sub_folder_name notes

  • Defines Sub folder for video file path destination (Optional):
    OverwolfVideoFolder\\AppName\\|sub_folder_name\\|file_name|
  • In case [sub_folder_name] is empty:
    OverwolfVideoFolder\\AppName\\|file_name|

VideoSource Object

Version added: 0.159

Container for secondary video sources' settings.

ParameterTypeDescription
source_typeoverwolf.media.enums.eSourceTypeThe video source type
namestringThe name of the source
secondary_filebooleanSource will be saved to a secondary video file (i.e. another ow-obs.exe process will be created with the same settings as the original one.
transformoverwolf.media.enums.eVideoSourceTransformHow should the video's source be transformed to fit the declared size
parametersoverwolf.media.replays.WebCamParamParameters specific to the selected source_type. Currently only "WebCam" is supported
position2DPoint{x, y}The position (in pixels) of the secondary source in the video
size_scale2DPoint{x, y}The size of the video source in the final video (on a scale of 0-1, relative to the screen size)

Usage example

let settings = {
"video": {
"buffer_length": 30,
"sources": [
{
"source_type": overwolf.media.replays.enums.eSourceType.WebCam,
"name":"webcam",
"secondary_file": true,
"transform": overwolf.media.replays.enums.eVideoSourceTransform.Stretch,
"parameters": { "device_id" : "default" },
"position": { x: 200, y: 200 } // offset is pixel relative to dock position (transform)
"size_scale" : { x: 0.25, y: 0.25 }// render size the source in stream (relative to video size), valid only when transform != eVideoSourceTransform.Stretch
}]
}
};

overwolf.media.replays.turnOn({
"settings": streamSetting,
"highlights": {
"enable" : true, //set false if you want to record the highligths manually
"requiredHighlights" : ["death","assist","victory"] // events to capture
}
}, callback);

WebCamParam Object

Version added: 0.159

Parameters for a VideoSource's webcam

ParameterTypeDescription
device_idstringThe device id for the selected webcam

ImageSource Object

Version added: 0.159

Parameters for a ImageSource's image

ParameterTypeDescription
filestringPath and name of file
transformenumoverwolf.media.enums.eVideoSourceTransform
scaleobject {"units": "<px | scale>", "width": "<int>", "height": "<int>"}The size of the image. scale is a percentage of the original image size and is a number between 0-1. px will be render the image in the size you chose.
position2DPoint {x y}

ReplayType enum

Version added: 0.78

The replay type to use.

OptionDescription
Video

TurnOnResult Object

Version added: 0.149

Container for the turnOn result.

ParameterTypeDescription
descriptionstring
metadatastring
mediaFolderstring
osVersionstring
osBuildstring
{
"success": true,
"status": "success", //deprecated and kept only for backward compatibility
"description": "",
"metadata": "",
"mediaFolder": "",
"osVersion": "",
"osBuild": ""
}

TurnOffResult Object

Version added: 0.149

Container for the turnOff result.

ParameterTypeDescription
descriptionstring
metadatastring
osVersionstring
osBuildstring
{
"success": true,
"status": "success", //deprecated and kept only for backward compatibility
"description": "",
"metadata": "",
"osVersion": "",
"osBuild": ""
}