Skip to content
This repository was archived by the owner on Sep 1, 2024. It is now read-only.

media.mdx

Latest commit

 

History

History
517 lines (388 loc) · 25 KB

media.mdx

File metadata and controls

517 lines (388 loc) · 25 KB
id media
image /img/embed/api-docs.jpg
title overwolf.media API
sidebar_custom_props
overwolf_platform electron_platform
true
false

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.

Parameter Type Description
callback (Optional) (Result: FileResult) => void A 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.

Parameter Type Description
targetFolder string Target screen shot folder path
callback (Result: FileResult) => void A 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.

Parameter Type Description
targetPath string Target screen shot file path
options (Optional) ScreenshotOptions Extra settings controlling the screenshot
callback (Optional) (Result: FileResult) => void A 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.

Parameter Type Description
windowHandle int The window handle number. The handle number can retrieved from overwolf.games.launchers.getRunningLaunchersInfo()
postMediaEvent bool set true to post (onMediaEvent)
callback (Result: FileResult) => void A 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.

Parameter Type Description
windowHandle int The window handle number. The handle number can retrieved from overwolf.games.launchers.getRunningLaunchersInfo()
postMediaEvent bool set true to post (onMediaEvent)
targetFolder string Set target folder path for screenshot
callback (Result: FileResult) => void A 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().

Parameter Type Description
windowTitle string The OS window title
postMediaEvent bool set true to post (onMediaEvent)
callback (Result: FileResult) => void A 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().

Parameter Type Description
windowTitle string The OS window title
postMediaEvent bool set true to post (onMediaEvent)
targetFolder string Set target folder path for screenshot
callback (Result: FileResult) => void A 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.
Parameter Type Description
screenshotParams MemoryScreenshotParams object A JSON containing the parameters of the screenshot
callback (optional) (Result: FileResult) => void A function called after the screenshot was taken

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);
        }
    }
);

Known Issues

overwolf.media.getScreenshotUrl in any DX12 game always returns the following result:

{
  success: false,
  status: 'error',
  error: 'Capture failed'
}

This is a known limitation of the current implementation. There is a workaround using overwolf.media.takeScreenshot and deleting the screenshot afterward but it's less performant.

shareImage(image, description, callback)

Version added: 0.78

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

Parameter Type Description
image Object A URL or image object to be shared
description string The description to be used when posting to social networks
callback (Result) => void Reports success or failure

postMediaEvent(mediaType, jsonInfo, callback)

Version added: 0.91

Posts a media event for other apps to receive.

Parameter Type Description
mediaType eMediaType enum The type of the event
jsonInfo JObject A json with additional info about the events
callback (Result) => void Reports 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.
Parameter Type Description
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.
Parameter Type Description
callback (Result: GetAppScreenCaptureFolderSizeResult) => void A callback with the size in MB

getWebcams(callback)

Version added: 0.159

Get all connected Webcams.

Parameter Type Description
callback (Result: GetWebcamsResult) => void A callback with the connected Webcams

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.

Parameter Type Description
imageFormat ImageFormat The file format to use for the taken image

MemoryScreenshotParams Object

Version added: 0.78

Container for memory screenshot settings.

Parameter Type Description
roundAwayFromZero bool When a number is halfway between two others, it is rounded toward the nearest number that is away from zero. Recommended for better precision
rescale RescaleParams Object The rescale settings
crop CropParams Object The crop settings

RescaleParams Object

Version added: 0.78

Describes rescale parameters for memory screenshot.

Parameter Type Description
width double The target width
height double The target height

CropParams Object

Version added: 0.78

Describes rescale parameters for memory screenshot.

Parameter Type Description
x double The x offset. Positive value is considered absolute (0 – WIDTH) and negative is considered relative (-1.0 – 0)
y double The y offset. Positive value is considered absolute (0 – HEIGHT) and negative is considered relative (-1.0 – 0)
width double The target width
height double The target height

ImageFormat enum

Version added: 0.226

Image format to use for a file screenshot.

Option Description
Jpeg .jpg
Bmp .bmp

eMediaType enum

Version added: 0.78

Media type for the Media Event.

Option Description
Video
Image

eSourceType enum

Version added: 0.159

Video source type.

Option Description
Webcam

eVideoSourceTransform enum

Version added: 0.159

Video transform type.

Option Description
Stretch

FileResult Object

Version added: 0.149

Container for get file URL result.

Parameter Type Description
url string
path string

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.

Parameter Type Description
totalVideosSizeMB number

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.

Parameter Type Description
WebCams overwolf.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.

Parameter Type Description
name string
path string
id string

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"
},

GetAppScreenCaptureFolderSizeResult Object

Version added: 0.149

Container for get file getAppVideoCaptureFolderSize result.

Parameter Type Description
screenCaptureSizeMB number

Example data: Success

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

ScreenshotTakenEvent Object

Parameter Type Description
url string

Event data example: Success

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