Skip to main content

overwolf.media API

Use this API to capture a screenshot of the currently running game.

Permissions required: Media

Methods Reference​

Events Reference​

Types Reference​

In-memory screenshot overview​

Some methods in the overwold.media API allows you to take in-memory screenshot.

For example, the takeScreenshot(callback) method returns in a callback argument a screenshot URL that looks like this:

overwolf://media/screenshots/custom/E:/Desktop%20Capture-07-15-2018%2014-15-22-793.jpg

You can use the retrieved URL later in order to serve the stated screenshot: for example, to upload it to remote server, you can use HTML canvas.

Sample app​

Download here a Sample app for using the In-Memory Screenshot API.

takeScreenshot(callback)​

Version added: 0.78​

Takes a screenshot and calls the callback with the success status and the screenshot URL. The screenshot is saved to the screenshots folder.

note

As of version 0.310.0.16, this method processes on the GPU for every graphics API and is subject to the same per-app capture rate limit as getScreenshotUrl().

ParameterTypeDescription
callback (Optional)(Result: FileResult) => voidA function called after the screenshot was taken

takeScreenshot(targetFolder, callback)​

Version added: 0.117​

Takes a screenshot and calls the callback with the success status and the screenshot URL. The screenshot is saved to the screenshots folder.

ParameterTypeDescription
targetFolderstringTarget screen shot folder path
callback(Result: FileResult) => voidA callback function which will be called with the status of the request and the screenshot URL.

takeScreenshotEx(targetPath, options, callback)​

Version added: 0.226​

Takes a screenshot and calls the callback with the success status and the screenshot URL. The screenshot is saved to the screenshots folder.

note

As of version 0.310.0.16, this method processes on the GPU for every graphics API and is subject to the same per-app capture rate limit as getScreenshotUrl().

ParameterTypeDescription
targetPathstringTarget screen shot file path
options (Optional)ScreenshotOptionsExtra settings controlling the screenshot
callback (Optional)(Result: FileResult) => voidA callback function which will be called with the status of the request and the screenshot URL.

takeWindowsScreenshotByHandle(windowHandle, postMediaEvent, callback)​

Version added: 0.115​

Takes a window screenshot and calls the callback with the success status and the screenshot URL. The screenshot is saved to the screenshots folder.

ParameterTypeDescription
windowHandleintThe window handle number. The handle number can retrieved from overwolf.games.launchers.getRunningLaunchersInfo()
postMediaEventboolset true to post (onMediaEvent)
callback(Result: FileResult) => voidA function called after the screenshot was taken

takeWindowsScreenshotByHandle(windowHandle, postMediaEvent, targetFolder, callback)​

Version added: 0.115​

Takes a window screenshot and calls the callback with the success status and the screenshot URL. The screenshot is saved to the screenshots folder.

ParameterTypeDescription
windowHandleintThe window handle number. The handle number can retrieved from overwolf.games.launchers.getRunningLaunchersInfo()
postMediaEventboolset true to post (onMediaEvent)
targetFolderstringSet target folder path for screenshot
callback(Result: FileResult) => voidA function called after the screenshot was taken

takeWindowsScreenshotByName(windowTitle, postMediaEvent, callback)​

Version added: 0.115​

Takes a window screenshot and calls the callback with the success status and the screenshot URL. The screenshot is saved to the screenshots folder.

This function is to capture a native OS window by it's OS window Title - for example - "Untitled - Notepad".
To capture one of your app's windows you should use HTML5 Canvas.toDataURL().

ParameterTypeDescription
windowTitlestringThe OS window title
postMediaEventboolset true to post (onMediaEvent)
callback(Result: FileResult) => voidA function called after the screenshot was taken

takeWindowsScreenshotByName(windowTitle, postMediaEvent, targetFolder, callback)​

Version added: 0.117​

Takes a window screenshot and calls the callback with the success status and the screenshot URL. The screenshot is saved to the targetFolder folder.

This function is to capture a native OS window by it's OS window Title - for example - "Untitled - Notepad".
To capture one of your app's windows you should use HTML5 Canvas.toDataURL().

ParameterTypeDescription
windowTitlestringThe OS window title
postMediaEventboolset true to post (onMediaEvent)
targetFolderstringSet target folder path for screenshot
callback(Result: FileResult) => voidA function called after the screenshot was taken

getScreenshotUrl(screenshotParams, callback)​

Version added: 0.85​

Takes a memory screenshot and calls the callback with the success status and the screenshot URL.

  • The screenshot will only be placed in the memory and will not be saved to a file (better performance).
  • Can only be used while in a game.
  • You can take a look at the in-memory screenshot sample app.
  • You can read more about the in-memory screenshot here.
ParameterTypeDescription
screenshotParamsMemoryScreenshotParams objectA JSON containing the parameters of the screenshot
callback (optional)(Result: FileResult) => voidA function called after the screenshot was taken
note

As of version 0.310.0.16, cropping and rescaling run on the GPU for every graphics API: DirectX 9, DirectX 11, DirectX 12, Vulkan, OpenGL, and OOPO games. Before 0.310.0.16, a sized capture in a Vulkan title was decoded, resized on the CPU, and re-encoded; that extra step, and the "avoid rescaling in Vulkan" guidance that came with it, no longer applies.

Capture behavior changes (0.310.0.16)
  • One capture in flight per app. Calling getScreenshotUrl() again before the previous callback returns is refused, not queued. Chain the next call from the callback instead of a timer.
  • Captures are rate limited to 30 per second with a burst allowance, tracked per app rather than shared across the whole client.
  • A capture that can't be submitted now reports failure. Previously such a request was silently dropped and the callback was never called. You now get success: false with an error.
  • Rescaled output uses mip filtering, so downscaled images have less aliasing than before, particularly on thin strokes. If you compare captures against stored reference images, regenerate them.

Usage Example​

overwolf.media.getScreenshotUrl(
    {
        //Recommended for better rounding.
        roundAwayFromZero : "true",
        //Optional - Crop the screen (happens before the rescale, if both are used).
        //Positive values are absolute, negative values are relative (-1.0 - 0)
        crop: {
            x: -0.5, //Start cropping at the middle of the screen
            y: 0,
            width: 400,
            height: -0.5
        },
        //Optional - Rescale the final image to these dimensions
        rescale: {
            width: 1920,
            height: -0.4
        }
    },
    function(result) {
        if (result.status == "success")
        {
            console.log(result.url);
        }
    }
);

createScreenshotBuffer(params, callback)​

Version added: 0.310.0.16​

Creates a reusable screenshot buffer handle. Call capture() on the returned handle to grab raw pixels straight into an ArrayBuffer, with no encode, decode, or file round trip.

Use this when you only need to read pixels (recognition, OCR, color sampling in a loop). The buffer holds raw pixels, not an image file, so you cannot set img.src from it. Use getScreenshotUrl() when the capture is meant to be displayed. Not supported on DX9 games.

ParameterTypeDescription
paramsCreateScreenshotBufferParams objectPixel format, crop, and rescale settings, fixed once for this handle
callback(Result: CreateScreenshotBufferResult) => voidA function called with the created handle

A handle can be created before any game is running, since it only stores settings. The absence of a game is reported per capture() call, not at creation. Your app may hold up to 16 open handles at once; call close() on handles you're done with.

Usage Example​

overwolf.media.createScreenshotBuffer(
  {
    format: 'rgba', // or 'bgra', 'gray8'
    crop: { x: 0, y: 0, width: 640, height: 480 },
    rescale: { width: 320, height: 240 },
    roundAwayFromZero: false
  },
  (createResult) => {
    if (!createResult.success) {
      console.error(createResult.error);
      return;
    }

    const handle = createResult.screenshotBuffer;
    // handle.capture(...) to grab a frame, handle.close() when done
  }
);

Capture loop example​

Create the handle once, then chain each capture() call from the previous callback, never from setInterval:

let handle = null;
let running = false;

function startLoop() {
    overwolf.media.createScreenshotBuffer({ format: 'gray8' }, (r) => {
        if (!r.success) {
            console.error(r.error);
            return;
        }

        handle = r.screenshotBuffer;
        running = true;
        grab();
    });
}

function grab() {
    handle.capture((f) => {
        if (!running) {
            return;
        }

        if (!f.success) {
            console.error(f.error);
            stopLoop();
            return;
        }

        const gray = new Uint8Array(f.buffer);
        // gray[y * f.stride + x] is the luminance of one pixel.

        grab();   // chain from the callback, never setInterval
    });
}

function stopLoop() {
    running = false;

    if (handle) {
        handle.close();
        handle = null;
    }
}

Errors​

ErrorCause
No parameters providedPass at least {}.
Unsupported format '<x>'. Supported: 'rgba', 'bgra', 'gray8'. For an encoded image use overwolf.media.getScreenshotUrl.An encoded format such as png or jpg was requested. Use getScreenshotUrl() instead.
too many open screenshot buffers (<n>) - close the ones you have finished withThe 16-handle-per-app limit was hit. Call close() on unused handles.
Width and/or height provided in the rescale params are either <= 0 or width > 2560 or height > 1440.rescale out of bounds.
One of the crop inputs is below -1.0 ... / Requested image dimensions are out of bounds ...crop out of bounds.

screenshotBuffer.capture(callback)​

Version added: 0.310.0.16​

Grabs one frame using the handle's fixed settings.

ParameterTypeDescription
callback(Result: CaptureFrameResult) => voidA function called with the captured frame

Only one capture at a time per handle. Calling capture() again while a previous call on the same handle is still pending fails immediately with success: false; it is not a thrown exception, so a try/catch around the call does not see it. The capture already running is unaffected and still delivers its own callback. This is deliberate back pressure: chain the next capture() from the callback, never from a timer faster than captures complete.

Errors​

ErrorCause
a capture is already in progress on this buffer - wait for its callbackAnother capture() on this handle is still pending.
this screenshot buffer is closedclose() was already called, or the window that created the handle was closed.
No game is runningNothing to capture yet.
capture did not return raw pixels / Capture failedThe capture engine could not produce a frame.
could not create the ArrayBuffer ...The frame arrived but could not be handed to JavaScript.
note

A game's back-buffer alpha is whatever its last shader left there, often fully transparent. capture() always replaces it with fully opaque alpha, so you can draw the buffer (for example with putImageData) without touching the alpha channel yourself. This applies only to this raw path; getScreenshotUrl() is unaffected.

screenshotBuffer.close()​

Version added: 0.310.0.16​

Releases the handle and its slot against the 16-handles-per-app limit. Any later capture() on it fails with this screenshot buffer is closed.

The handle is also released when the window that created it closes, so forgetting close() leaks nothing permanently, but it holds a slot until then.

shareImage(image, description, callback)​

Version added: 0.78​

Opens the social network sharing console to allow the user to share a picture.

ParameterTypeDescription
imageObjectA URL or image object to be shared
descriptionstringThe description to be used when posting to social networks
callback(Result) => voidReports success or failure

postMediaEvent(mediaType, jsonInfo, callback)​

Version added: 0.91​

Posts a media event for other apps to receive.

ParameterTypeDescription
mediaTypeeMediaType enumThe type of the event
jsonInfoJObjectA json with additional info about the events
callback(Result) => voidReports success or failure

getAppVideoCaptureFolderSize(callback)​

Version added: 0.106​

Returns the total size of the video capture folder created by the app. This includes all video/thumbnail and other files that are under the apps video folder.

  • The apps video folder is located inside the configured Overwolf video capture folder.
  • This function can take a long time to return if the folder contains a large amount of files (on some computers) – therefore, try to reduce the amount of times you call it.
ParameterTypeDescription
callback(Result: GetAppVideoCaptureFolderSizeResult) => void A callback with the size in MB

getAppScreenCaptureFolderSize(callback)​

Version added: 0.106​

Returns the total size of the screen capture folder created by the app. This includes all images/thumbnail and other files that are under the apps images folder.

  • The apps imagee folder is located inside the configured Overwolf image capture folder.
  • This function can take a long time to return if the folder contains a large amount of files (on some computers) – therefore, try to reduce the amount of times you call it.
ParameterTypeDescription
callback(Result: GetAppScreenCaptureFolderSizeResult) => void A callback with the size in MB

getWebcams(callback)​

Version added: 0.159​

Get all connected Webcams.

ParameterTypeDescription
callback(Result: GetWebcamsResult) => void A callback with the connected Webcams

isXboxDVREnabled(callback)​

Version added: 0.305.0.7​

Returns whether Xbox Game DVR is enabled.

ParameterTypeDescription
callback(Result: XboxDVRStatusResult) => voidA callback with the Xbox Game DVR status.

disableXboxDVR(callback)​

Version added: 0.305.0.7​

Disables Xbox Game DVR for the current user.

ParameterTypeDescription
callback(Result) => voidA callback with the status of the request.

onMediaEvent​

Version added: 0.78​

Fired when a media event has been posted.

Event Data Example: Success​

 {
  "origin": "nafihghfcpikebhfhdhljejkcifgbdahdhngepfb",
  "triggerTime": "2018-10-22T16:56:39.000Z",
  "events": [
    "death"
  ],
  "rawEvents": [
    {
      "type": "death",
      "time": 15000
    }
  ],
  "mediaUrl": "overwolf://media/replays/Game+Summary/Fortnite/Fortnite_22-10-2018_19-53-40-1/Fortnite+10-22-2018+19-56-39-385.mp4",
  "thumbnailUrl": "overwolf://media/thumbnails/Game+Summary/Fortnite/Fortnite_22-10-2018_19-53-40-1/Fortnite+10-22-2018+19-56-39-385.mp4",
  "fullDuration": 20015,
  "eventsDuration": 5015
}

onScreenshotTaken​

Version added: 0.78​

Fired when a screenshot was taken, with the following structure: ScreenshotTakenEvent Object

ScreenshotOptions Object​

Version added: 0.226​

Container for file screenshot settings.

ParameterTypeDescription
imageFormatImageFormatThe file format to use for the taken image

MemoryScreenshotParams Object​

Version added: 0.78​

Container for memory screenshot settings.

ParameterTypeDescription
roundAwayFromZeroboolWhen a number is halfway between two others, it is rounded toward the nearest number that is away from zero. Recommended for better precision
rescaleRescaleParams ObjectThe rescale settings
cropCropParams ObjectThe crop settings

RescaleParams Object​

Version added: 0.78​

Describes rescale parameters for memory screenshot.

ParameterTypeDescription
widthdoubleThe target width
heightdoubleThe target height

CropParams Object​

Version added: 0.78​

Describes rescale parameters for memory screenshot.

ParameterTypeDescription
xdoubleThe x offset. Positive value is considered absolute (0 – WIDTH) and negative is considered relative (-1.0 – 0)
ydoubleThe y offset. Positive value is considered absolute (0 – HEIGHT) and negative is considered relative (-1.0 – 0)
widthdoubleThe target width
heightdoubleThe target height

CreateScreenshotBufferParams Object​

Version added: 0.310.0.16​

Settings for a screenshot buffer handle, fixed once at creation.

ParameterTypeDescription
formatstring'rgba' (default), 'bgra', or 'gray8'. rgba is 4 bytes/pixel and the only one ImageData accepts without reordering. gray8 is 1 byte/pixel, the cheapest for recognition work. Encoded formats (png, jpg) are not accepted; use getScreenshotUrl() for those.
cropCropParams objectSame crop settings getScreenshotUrl() accepts.
rescaleRescaleParams objectSame rescale settings getScreenshotUrl() accepts. Runs on the GPU on every renderer, Vulkan included.
roundAwayFromZeroboolRounds halfway values away from zero. Recommended for better precision. Default false.

ScreenshotBuffer Object​

Version added: 0.310.0.16​

The reusable handle returned by createScreenshotBuffer().

MethodDescription
capture(callback)Grabs one frame with this handle's fixed settings.
close()Releases the handle and its slot.

CreateScreenshotBufferResult Object​

Version added: 0.310.0.16​

Result of createScreenshotBuffer().

ParameterTypeDescription
successboolean
statusstring"error" when success is false
errorstringSet only when success is false
screenshotBufferScreenshotBuffer objectThe handle, only when success is true

CaptureFrameResult Object​

Version added: 0.310.0.16​

Result of screenshotBuffer.capture().

ParameterTypeDescription
successboolean
statusstring"error" when success is false
errorstringSet only when success is false
widthnumberWidth of the delivered image, in pixels
heightnumberHeight of the delivered image, in pixels
stridenumberBytes per row. Rows are packed, so stride === width * bytesPerPixel and buffer.byteLength === stride * height
formatstringThe pixel layout actually delivered: 'rgba', 'bgra', or 'gray8'
bufferArrayBufferThe pixels. Alpha is always fully opaque.

ImageFormat enum​

Version added: 0.226​

Image format to use for a file screenshot.

OptionDescription
Jpeg.jpeg
Bmp.bmp
Screenshot Formats

Screenshots taken before version 0.226 were always saved as a .jpg. If your app needs to handle those screenshots as well, make sure it can handle both .jpeg and .jpg images (as well as .bmp if relevant)

eMediaType enum​

Version added: 0.78​

Media type for the Media Event.

OptionDescription
Video
Image

eSourceType enum​

Version added: 0.159​

Video source type.

OptionDescription
Webcam
Generic
image_source

eVideoSourceTransform enum​

Version added: 0.159​

Video transform type.

OptionDescription
Stretch
DockTopLeft
DockTopMiddle
DockTopRight
DockMiddleLeft
DockCenter
DockMiddleRight
DockBottomLeft
DockBottomMiddle
DockBottomRight

FileResult Object​

Version added: 0.149​

Container for get file URL result.

ParameterTypeDescription
urlstring
pathstring

Example data: Success​

{
   "success": true,
   "status": "success", //deprecated and kept only for backward compatibility
   "url": "overwolf://media/replays/App+Name/Dota+2+06-28-2016+17-59-37-620.mp4",
   "path": "E://Video/Overwolf/App Name/Dota 2 06-28-2016 17-59-37-620.mp4"
}

Note that the last part of the file name is the replayId. In the above example, it's 620.
The replayId is needed to finish capturing the replay by calling for example to overwolf.media.replays.stopCapture(). In the above example, it's 620.

GetAppVideoCaptureFolderSizeResult Object​

Version added: 0.149​

Container for get file getAppVideoCaptureFolderSize result.

ParameterTypeDescription
totalVideosSizeMBnumber

Example data: Success​

{
   "success": true,
   "status": "success", //deprecated and kept only for backward compatibility
   "totalVideosSizeMB": 12123,
}

GetWebcamsResult Object​

Version added: 0.159​

Container for get Webcams result.

ParameterTypeDescription
WebCamsoverwolf.media.Webcam[]

Example data: Success​

{
   "success": true,
   "status": "success", //deprecated and kept only for backward compatibility
   "webCams ": [
      {
        "name":"Webcam C170",
        "path":"\\\\?\\usb#vid_046d&pid_082b&mi_00#7&2c79cd0&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global",
        "id":"Webcam C170:\\\\?\\usb#vid_046d&pid_082b&mi_00#7&2c79cd0&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global"
      },
      {
        "name":"USB2.0 HD UVC WebCam",
        "path":"\\\\?\\usb#vid_13d3&pid_5666&mi_00#6&2f2fc667&1&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global",
        "id":"USB2.0 HD UVC WebCam:\\\\?\\usb#vid_13d3&pid_5666&mi_00#6&2f2fc667&1&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global"
      },
      {
        "name":"OBS Virtual Camera",
        "path":"",
        "id":"OBS Virtual Camera:"
      }
   ],
}

Webcam Object​

Version added: 0.159​

Container for Webcam proporties.

ParameterTypeDescription
namestring
pathstring
idstring

Data example​

{
  "name":"Webcam C170",
  "path":"\\\\?\\usb#vid_046d&pid_082b&mi_00#7&2c79cd0&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global",
  "id":"Webcam C170:\\\\?\\usb#vid_046d&pid_082b&mi_00#7&2c79cd0&0&0000#{65e8773d-8f56-11d0-a3b9-00a0c9223196}\\global"
},

XboxDVRStatusResult Object​

Version added: 0.305.0.7​

Container for the Xbox Game DVR status.

ParameterTypeDescription
enabledboolWhether Xbox Game DVR is enabled.
appCaptureEnabledboolWhether the current user has app capture enabled.
gameDVREnabledboolWhether the current user has Game DVR enabled.

GetAppScreenCaptureFolderSizeResult Object​

Version added: 0.149​

Container for get file getAppVideoCaptureFolderSize result.

ParameterTypeDescription
screenCaptureSizeMBnumber

Example data: Success​

{
   "success": true,
   "status": "success", //deprecated and kept only for backward compatibility
   "screenCaptureSizeMB": 12123,
}

ScreenshotTakenEvent Object​

ParameterTypeDescription
urlstring

Event data example: Success​

{
  "success": true,
  "url": ""
}