XAppCaptureRecordTimespan

2025-04-28

Makes a GameDVR recording. There is no UI to indicate that such a recording is being made. The user does not have access to the recording. At most 2 such recordings can be made at any given time. Once 2 recordings are made, XAppCaptureCloseLocalStream will need to be called to close & delete a recording before another recording can be made. This can be used to capture past or future activity.

Syntax

HRESULT XAppCaptureRecordTimespan(
  const SYSTEMTIME * startTimestamp,
  uint64_t durationInMilliseconds,
  XAppCaptureLocalResult * result
)

Parameters

startTimestamp _In_opt_
Type: const SYSTEMTIME *

The timestamp to start recording from. This parameter can be null, in which case the system will automatically calculate the start time as durationInMilliseconds in the past and the recording will contain past activities.

durationInMilliseconds _In_
Type: uint64_t

Length of recording in milliseconds.

result _Out_
Type: XAppCaptureLocalResult *

On function completion, contains the capture results. See XAppCaptureReadLocalStream for how the resulting recording can be read.

Return value

Type: HRESULT

Function result.

The function will return E_ACCESSDENIED if the user's GameDVR setting forbids games from making captures.

Remarks

There are two ways to pass in the startTimestamp parameter to record past activity.

In the first, null is passed. The system will automatically calculate the timestamp and record past activities that are durationInMilliseconds long from now.

Note

Older clips will be deleted when allotted space is filled to make room for new clips. Use PLS (Persistent Local Storage), connected storage (e.g. XGameSave or XGameSaveFiles), or a similar storage system in order to retain clips for a set period of time.

XAppCaptureLocalResult appCaptureLocalResult = { 0 };
uint64_t durationInMs = 5000; /* 5 seconds, for example */

if (SUCCEEDED(XAppCaptureRecordTimespan(nullptr, durationInMs, &appCaptureLocalResult))) // record the past 5000ms (startTimestamp is calculated automatically)
{
    appLog.AddLog("StartTimestamp: %llu, Duration (ms): %llu, File Size (bytes): %llu, Width: %d, Height: %d, Encoding: %d, Color Format: %d\n", appCaptureLocalResult.clipStartTimestamp, appCaptureLocalResult.durationInMilliseconds, appCaptureLocalResult.fileSizeInBytes,
        appCaptureLocalResult.width, appCaptureLocalResult.height, appCaptureLocalResult.encoding, appCaptureLocalResult.colorFormat);
}

In the second, you must calculate your desired start timestamp by converting SYSTEMTIME or FILETIME to ULARGE_INTEGER, doing the required arithmetic, then converting ULARGE_INTEGER back to SYSTEMTIME.

void SubtractMsDurationFromFileTimeToULarge(_In_ FILETIME* pFileTime, _In_ uint64_t durationInMs, _Out_ ULARGE_INTEGER* pUlResultingTime)
{
    ULARGE_INTEGER fileTimeAsUlarge;

    fileTimeAsUlarge.LowPart = pFileTime->dwLowDateTime;
    fileTimeAsUlarge.HighPart = pFileTime->dwHighDateTime;

    // Convert ms to 100 ns intervals, the convention used by FILETIME
    pUlResultingTime->QuadPart = fileTimeAsUlarge.QuadPart - (durationInMs * 10000LL);
}

void ULargeToSystemTime(_In_ ULARGE_INTEGER ulInputTime, _Out_ SYSTEMTIME* pOutputTime)
{
    FILETIME inputAsFiletime;

    inputAsFiletime.dwLowDateTime = ulInputTime.LowPart;
    inputAsFiletime.dwHighDateTime = ulInputTime.HighPart;

    FileTimeToSystemTime(&inputAsFiletime, pOutputTime);
}

void YourFunction()
{
    XAppCaptureLocalResult appCaptureLocalResult = { 0 }; 
    uint64_t durationInMs = 8000; /* 8 seconds, for example */
    FILETIME now;
    ULARGE_INTEGER calculatedStartTimestamp;
    SYSTEMTIME startTimestampAsSystemTime;
    XAppCaptureVideoCaptureSettings captureSettings = { 0 };

    GetSystemTimeAsFileTime(&now);
    SubtractMsDurationFromFileTimeToULarge(&now, durationInMs, &calculatedStartTimestamp);
    ULargeToSystemTime(calculatedStartTimestamp, &startTimestampAsSystemTime);
    
    if (SUCCEEDED(XAppCaptureGetVideoCaptureSettings(&captureSettings)) && captureSettings.isCaptureByGamesAllowed && (captureSettings.maxRecordTimespanDurationInMs >= durationInMs)){
        if (SUCCEEDED(XAppCaptureRecordTimespan(&startTimestampAsSystemTime, durationInMs, &appCaptureLocalResult))) // record 8000ms starting from 8000ms before now (calculated manually)
        {
            appLog.AddLog("StartTimestamp: %llu, Duration (ms): %llu, File Size (bytes): %llu, Width: %d, Height: %d, Encoding: %d, Color Format: %d\n", appCaptureLocalResult.clipStartTimestamp, appCaptureLocalResult.durationInMilliseconds, appCaptureLocalResult.fileSizeInBytes,
                appCaptureLocalResult.width, appCaptureLocalResult.height, appCaptureLocalResult.encoding, appCaptureLocalResult.colorFormat);
        }
    }
}

XAppCaptureRecordTimespan can also be used to record the next durationInMilliseconds milliseconds of activity by specifying startTimestamp as the current system time.

XAppCaptureLocalResult appCaptureLocalResult = { 0 }; 
uint64_t durationInMs = 10000; /* 10 seconds, for example */
SYSTEMTIME nowStartTimestamp;
XAppCaptureVideoCaptureSettings captureSettings = { 0 };

GetSystemTime(&nowStartTimestamp);

if (SUCCEEDED(XAppCaptureGetVideoCaptureSettings(&captureSettings)) && captureSettings.isCaptureByGamesAllowed){
    if (SUCCEEDED(XAppCaptureRecordTimespan(&nowStartTimestamp, durationInMs, &appCaptureLocalResult))) // record the next 10 seconds starting now
    {
        appLog.AddLog("StartTimestamp: %llu, Duration (ms): %llu, File Size (bytes): %llu, Width: %d, Height: %d, Encoding: %d, Color Format: %d\n", appCaptureLocalResult.clipStartTimestamp, appCaptureLocalResult.durationInMilliseconds, appCaptureLocalResult.fileSizeInBytes,
            appCaptureLocalResult.width, appCaptureLocalResult.height, appCaptureLocalResult.encoding, appCaptureLocalResult.colorFormat);
    }
}

See XAppCaptureLocalResult and XAppCaptureReadLocalStream

Requirements

Header: XAppCapture.h

Library: xgameruntime.lib

Supported platforms: Windows, Xbox One family consoles and Xbox Series consoles

Share via