Window & Game Capture Compatibility Data - obsproject/obs-studio GitHub Wiki
Pull request 8080 introduced compatibility notices for Window and Game Capture directly in the UI:
These messages are intended to reduce support requests by informing the user about possible compatibility issues - and their resolutions - directly in the UI.
This data can be updated independently of OBS Studio itself in response to new game releases or incompatibilities due to third-party application updates.
New entries are added via pull requests to the obs-studio repository. To create a new entry, the following steps must be taken:
- Fork the OBS repo
- Clone your fork and create a new branch, e.g.
compatibility-<app name> - Add a new entry to
plugins/win-capture/data/compatibility.json- The easiest way of doing this is by copying an existing entry and adjusting it
- Entries are grouped by translation key and sorted by name within those groups, this is not enforced, but please try to keep things ordered!
- (Optional) Add new translation key to
plugins/win-capture/data/locale/en-US.ini - Increment the version number in
plugins/win-capture/data/package.json - Add and commit your changes with a brief message explaining the change (e.g.
win-capture: Add compatibility entry for <Game>) - Submit a pull request
Note that entries should only be added for reasonably popular applications that often come up in support channels such as the forums or Discord.
The compatibility information is stored in a JSON file. While not necessarily intended to be a human-readable format, it is still fairly easy to add a new entry.
Each entry in the file consists of the following fields:
| Field | Description |
|---|---|
name |
Name of the affected application(s) |
translation_key |
Translatable message to use |
message |
Fallback in case translation key is unavailable (English only) |
url |
Optional URL providing additional information |
severity (integer) |
Severity (0 = Notice, 1 = Warning, 2 = Error) |
match_flags (integer) |
Matching type (see previous section) |
excutable |
Executable name including extension (case-insensitive) |
window_class |
Window class (case-sensitive) |
window_title |
Window title (case-sensitive) |
game_capture (bool) |
Whether or not this entry affects game capture |
window_capture (bool) |
Whether or not this entry affects BitBlt Window Capture |
window_capture_wgc (bool) |
Whether or not this entry affects WGC Window Capture |
At least name, message, match_flags, and one of executable/window_class/window_title must be specified.
The matching done is decided via flags that are as follows:
| Type | Value |
|---|---|
| Match executable | 1 |
| Match title | 2 |
| Match class | 4 |
These behave as bitflags, and may be combined via a | b. For instance, if you wish to match both window name and executable specify it as 1 | 4 = 5.
Note that class and title are matched case-sensitively, but executables are matched insensitively. Executable names must also contain the file extension.
Window titles support prefix matches, i.e. if the window title starts with the specified string it is considered a match. This is useful for applications that have additional information after the title, such as a version number, like "Minecraft 1.18".
An entry's severity level is an integer with the following values:
| Severity | Value |
|---|---|
| Info | 0 |
| Warning | 1 |
| Error | 2 |
Severity levels decide how the message is presented to the user. "Info" messages are displayed in plain text, while "Warning" and "Error" messages are highlighted in different colours (orange and red, respectively).
They should be used as follows:
-
Errorshould be used if an application cannot be captured using the affected source type(s) -
Warningshould be used for correctable errors (e.g., change a game or source setting) -
Infoshould be used to provide tips in cases where there is no strict incompatibility.
Each entry shoud specify a translation_key that matches one of the Compatibility.* entries in en-US.ini. If none exists, a new one should be created when the compatibility list is updated. The message value is used as fallback until an OBS update containing the updated localisation data is shipped.
The translatable messages are split into two categories:
- Generic entries are for common issues (e.g. requiring running as admin, BitBlt capture not working) and can be reused as they support replacing a placeholder with the name specified in the compatibility entry.
- Application specific entries should only be added if fitting generic messages exist, and the issue is not something expected to affect other applications
When adding new messages, they should follow the same pattern of Compatibility.<Method>.<Issue> for generic messages, and Compatibility.Application.<App Name> for application-specific messages.
Translation texts support the %name% placeholder, this is mostly used in generic messages like so:
Compatibility.GameCapture.Admin="%name% may require OBS to be run as admin to use Game Capture."Specific messages should use the application name as the key and may not contain spaces. If the name consists of more than one word, then a commonly used abbreviation should be used instead, for instance, "Counter-Strike: Global Offensive" can be shortened to "CSGO":
Compatibility.Application.CSGO="CS:GO may require the <code>--allow_third_party_software</code> launch option to use Game Capture."