TFBRecorder Methods

TFBRecorder Methods

Note: usage examples are C#. For C++, Python and C# code see this page for a simple example and look in the /Samples folder in the SDK install folder for more detailed code.

Initialization

TFBRecorder()

The constructor.

Parameters:

Usage:

C#

// no logging, no licence
pRecorder = new TFBRecorder("","",0,0);

// create log files, no licence
pRecorder = TFBRecorder("", "c:\\myloggingfolder\\", 50, TFBRecorder.TLogKind.Verbose);

C++

// no logging, no licence
ptr = new FBRecorder::TFBRecorder(wsPathToFBRecorderDLL,"","", 0, 0);

// create log files, no licence
ptr = new FBRecorder::TFBRecorder(wsPathToFBRecorderDLL,"", "c:\\myloggingfolder\\", 10, FBRecorder::TLogKind::Verbose);

Python

// no logging, no licence
fbRecorder = FBRecorder(sPathToFBRecorderDLL, "", "", 0, 0) 

// create log files, no licence
fbRecorder = FBRecorder(sPathToFBRecorderDLL, "", "C:\\folder_for_log_files\\", 32, LogKind.Verbose) 

InitRecorder(sFileName)

Prepares the recorder for recording and sets the filename to save the recording to. The method must be called before each call to StartRecording.

Parameters:

Returns:

True for successful initialisation, false for failure.

Usage:

pRecorder = new TFBRecorder();

pRecorder.ActivateProfile(SAFE_SCREEN);

if (!pRecorder.InitRecorder("c:\\Users\\MyUser\\Videos\\myrecording.mp4")){
// there was an error
}

pRecorder.StartRecording();

~TFBRecorder()

The destructor. No parameters. Should be called to release resources held by the recorder.

Configuration

ActivateProfile(int iProfileId)

Sets the Recorder options to use a specified profile.

More about profiles.

Parameters:

Usage:

// record the screen using a high performance method and also record the PC sounds.

pRecorder.ActivateProfile(HIGH_SCREEN_AUDIO);

pRecorder.StartRecording(); 

GetConfigJSONForProfile(int iProfileId)

Fetches the specified profile as a JSON object string, so options can be changed and sent to the recorder object using SetConfigJSON.

See more about profiles.

Read about setting recorder options with the Config object.

Parameters:

Returns:

The settings corresponding to the profile, as a JSON object string.

When using the Python wrapper, GetConfigJSONForProfile returns a tuple <bool,string> where bool is the result of the function and string is the json object string.

Usage:

// get the HIGH_SCREEN options
json = pRecorder.GetConfigJSONForProfile(HIGH_SCREEN);

// change options to record a region 800x600 px<br />json["Region"]["Top"] = 100;<br />json["Region"]["Left"] = 100;
json[“Region“][“Width“] = 800;
json[“Region“][“Height“] = 600;

// and pass these options to the recorder
pRecorder.SetConfigJSON(json);

SetConfigJSON

Sets the options for the Recorder from the supplied JSON object string.

Read about setting recorder options with the Config object.

Parameters:

Returns

Boolean. True if the options were set successfully, False if not.

Usage:

if (!pRecorder.SetConfigJSON(sProfileConfigJSON))
{
   Console.WriteLine(“Error: unable to set a profile config json.”);
   goto end_of_func;
}
else
{
  pRecorder.StartRecording();
}

Recording

StartRecording

Starts recording, using the previously specified configuration and recording file.

Returns

Boolean. True if recording started successfully, False if not.

Usage:

if(!pRecorder.StartRecording())
{
// an error occurred
}

StopRecording

Stops recording.

Usage:

pRecorder.StopRecording();

Pause

Pauses or resumes recording.

Note: If the PC is suspended while recording is paused, this will result in a broken MP4 file. Your application should receive power setting notification functions from Windows and stop recording if the PC is being suspended.

Returns

Boolean. True if recording paused or resumed successfully, False if not.

Parameters:

Usage:

if(pRecorder.IsRecording())
{
  if (pRecorder.IsPaused())
    pRecorder.Pause(false); // resume the paused recording
  else
    pRecorder.Pause(true); // pause an in-progress recording
}

Editing

MergeMP4Files

Merges a number of MP4 files into one.

The sample code in the /Samples//ContinuousRecording/ folder uses this method to implement continuous recording – the application records the screen indefinitely using only a limited amount of disk space, and when it stops, saves the most recent seconds or minutes to an MP4 file. It achieves this by recording and saving a series of shorter MP4s and uses MergeMP4Files and CreateMP4Clip to construct an MP4 of the most recent minutes of recording.

Note: the meta data required for merging is written to the MP4 file only when StopRecording is called.
Note: very short MP4s written by version 5.0.0 of the SDK may not contain the meta data necessary for merging.

Parameters:

Returns:

Boolean. True if the merge was successful, False if not.

Usage:

C# (Newtonsoft json):
dynamic jsonFilenames = new JArray();

jsonFilenames.Add("C:\\yourfolder\\test_0.mp4");
jsonFilenames.Add("C:\\yourfolder\\test_1.mp4");
jsonFilenames.Add("C:\\yourfolder\\test_2.mp4");

string sJson = JsonConvert.SerializeObject(jsonFilenames, Formatting.Indented);

bool bResult =  TFBRecorder.MergeMP4Files(sJson, "C:\\yourfolder\\merged.mp4");

 
C++ (SimpleJSON):
json::JSON jsonFilenames;

jsonFilenames[0] = json::wstring_utf8(L"C:\\yourfolder\\test_0.mp4");
jsonFilenames[1] = json::wstring_utf8(L"C:\\yourfolder\\test_1.mp4");
jsonFilenames[2] = json::wstring_utf8(L"C:\\yourfolder\\test_2.mp4");

bool bResult = FBRecorder::TFBRecorder::MergeMP4Files(jsonMP4Files.dump().c_str(), L"C:\\yourfolder\\merged.mp4");

CreateMP4Clip

Saves a segment from an MP4 video file, as a new file.

Parameters:

if (StartTimeMs < 0) {
  StartTimeMs = 0;
}

if (StartTimeMs >= MovieLengthMs) {
  if (LengthMs > MovieLengthMs) {
    StartTimeMs = 0;
    LengthMs = MovieLengthMs;
  }
  else {
    StartTimeMs = MovieLengthMs - LengthMs;
  }
}

if (StartTimeMs + LengthMs > MovieLengthMs) {
  LengthMs = MovieLengthMs - StartTimeMs;
}

Returns:

Boolean. True if the clip was saved successfully, False if not.

Usage:

C# 
//
static void SaveAClip()
{
  string wsSourceMP4File = "C:\\yourfolder\\source_video.mp4";
  string wsMP4ClipFile = "C:\\yourfolder\\saved_clip.mp4";

  string appPath = AppDomain.CurrentDomain.BaseDirectory;
  
  // Run on trial, no licence.
  string wsLicence = "";

  // Create an instance of TFBRecorder. FBRecorder.dll needs to be in the same folder
  FBRecorder.TFBRecorder pResult = new FBRecorder.TFBRecorder(wsLicence);

  // save the first 20 seconds
  bool bResult = FBRecorder.TFBRecorder.CreateMP4Clip(wsSourceMP4File, 0, 20 * 1000, wsMP4ClipFile);
  if (!bResult)
    Console.WriteLine("Unable to create a clip.");
}

C++
//
void SaveAClip()
{
  std::wstring wsSourceMP4File = L"C:\\yourfolder\\source_video.mp4";
  std::wstring wsMP4ClipFile = L"C:\\yourfolder\\saved_clip.mp4";

  std::experimental::filesystem::path appPath(__argv[0]);
  
  // Run on trial, no licence.
  wchar_t wsLicence[] = L"";

  // Create an instance of TFBRecorder. FBRecorder.dll needs to be in the same folder
  std::shared_ptr pResult = std::shared_ptr(new FBRecorder::TFBRecorder(L"FBRecorder.dll", wsLicence));

  // Save the first 20 seconds of the video
  bool bResult = pResult->CreateMP4Clip(wsSourceMP4File.c_str(), 0, 20 * 1000, wsMP4ClipFile.c_str());

  if (!bResult)
    printf("Unable to create a clip.");
}

Misc

CanUse

Checks to see if the recorder can be used.

Returns:

Boolean. True if the options were set successfully, False if not.

Usage:

if (!pRecorder.SetConfigJSON(sProfileConfigJSON))
{
   Console.WriteLine(“Error: unable to set a profile config json.”);
   goto end_of_func;
}<br />else<br />{<br />   pRecorder.StartRecording();   <br />}

IsRecording

Checks to see if a recording is in progress.

Returns:

Boolean. True if a recording is in progress, False if not.

Usage:

if(pRecorder.IsRecording())
{
  if (pRecorder.IsPaused())
    pRecorder.Pause(false); // resume the paused recording
  else
    pRecorder.Pause(true); // pause an in-progress recording
}

IsPaused

Checks to see if there is an in progess recording that is paused.

Returns:

Boolean. True if a recording is in progress and paused, False if there is no in progress recording or there is, but it is not paused.

Usage:

if(pRecorder.IsRecording())
{
  if (pRecorder.IsPaused())
    pRecorder.Pause(false); // resume the paused recording
  else
    pRecorder.Pause(true); // pause an in-progress recording
}

CheckVideoEncoderAvailability

Checks to see if a particular video encoder can be used. The Type and Name of the encoder, as read from AvailableVideoEncoders are passed in.

Parameters:

Returns

Boolean. True if the encoder is available, False if not.

Usage:

if (!pRecorder.SetConfigJSON(sProfileConfigJSON))
{
   Console.WriteLine(“Error: unable to set a profile config json.”);
   goto end_of_func;
}<br />else<br />{<br />   pRecorder.StartRecording();   <br />}

Error Handling

InitializeLog

Initializes logging in TFBRecorder. Must be called before the constructor. Logging can either be initialized by this method or by passing parameters to the constructor.

Parameters:

Returns:

No return values.

Usage:

//setup recorder logging
string logFolder = Path.Combine(
   AppDomain.CurrentDomain.BaseDirectory,
   "FBRecorderTestCS");

Console.WriteLine("Log path folder: " + logFolder);

// Set verbose logging
TFBRecorder.InitializeLog(logFolder, 10, TFBRecorder.TLogKind.Verbose);

//create a recorder object
TFBRecorder pRecorderObject = new TFBRecorder();

if(!pRecorderObject.CanUse()) {
   Console.WriteLine("Error: unable to create a recorder object.");
   goto end_of_func;
}

StopLogging

Static method. Stops logging in TFBRecorder. Exit of the host application also stops logging.
Note: Previous to version 5.2 of the SDK, logging stopped when the FBRecorder instance was destroyed.

Parameters:

No parameters.

Returns:

No return values.

Usage:

//setup recorder logging
string logFolder = Path.Combine(
   AppDomain.CurrentDomain.BaseDirectory,
   "FBRecorderTestCS");

Console.WriteLine("Log path folder: " + logFolder);

// Set verbose logging
TFBRecorder.InitializeLog(logFolder, 10, TFBRecorder.TLogKind.Verbose);

// create a recorder object
TFBRecorder pRecorderObject = new TFBRecorder();

// do things...

TFBRecorder::StopLogging();

GetGlobalError

In the event of errors, methods add items to the global error list. GetGlobalError retrieves the error with the specified index, if it exists.

Parameters:

Returns:

The error code as defined in TFBRecorder.TFBGlobalError or TFBRecorder.TFBGlobalError.unknown if there is no error with that index.

Usage:

pRecorderObject.ResetGlobalErrors();
if (!pRecorderObject.InitRecorder(recordingFilename)) {
  Console.WriteLine("Error: unable to init recorder.");
  PrintGlobalErrors(pRecorderObject);
  goto end_of_func;
}

PrintGlobalErrors(pRecorderObject);
pRecorderObject.ResetGlobalErrors();

if (!pRecorderObject.StartRecording()) {
  PrintGlobalErrors(pRecorderObject);
  Console.WriteLine("Error: unable to start the recording.");
  goto end_of_func;
}

PrintGlobalErrors(pRecorderObject);

...

// Uses GetGlobalErrors to loop through errors and print them to the console
static void PrintGlobalErrors(TFBRecorder pRecorderObject)
{
  int iErrorIndex = 0;

  while (true) {
    TFBRecorder.TFBGlobalErrors Error = pRecorderObject.GetGlobalError(iErrorIndex);

    if (Error == TFBRecorder.TFBGlobalErrors.Unknown)
      break;

    Console.WriteLine("Error: " + Error);
    iErrorIndex++;
  }
}

ResetGlobalErrors

Resets the global errors list. It should be used before FBRecorder.init() and TFBRecorder.StartRecording().

Usage:

See usage of GetGlobalErrors.

Screen Capture

CaptureScreen

Captures the entire desktop, or a region, to a BMP, JPG or PNG file.

Parameters:

Returns:

No return values.

Usage:

if (pRecorder.CaptureScreen("d:/test.bmp", TFBRecorder.TFBRecorderImageFormat.BMP, 0, 0, 0, 800, 500))
  Console.WriteLine("Screen has been captured.");
else
  Console.WriteLine("Screen has NOT been captured.");

Export

ConvertMP4File

Exports an MP4 file as a video or audio file. The video container format can be set to MKV, AVI, WMV, GIF. H264 encoding is used in MKV and AVI formats. When performing an audio-only conversion, formats are AAC or MP3.

For more details, see the sample code.

Parameters:

Returns:

True if the conversion process completed, False if it did not. Use GetGlobalErrors to read error information in case of failure.

Usage:

Minimal code to convert an MP4 video file to MKV. Video only.

static bool ConvertExportMKVSimplified(TFBRecorder pFBRecorder)
{
  // The options for the conversion. We pass this to ConvertMP4File
  dynamic ConvertOpts = new JObject();
  ConvertOpts["ExportType"] = (int)FBRecorder.TFBRecorder.TExportType.mkv;

  // Options for the encoder. This gets added to the ConvertOpts object.
  JObject EncoderParams = new JObject();
  EncoderParams["VideoEncoder"] = new JObject();

  // Get an FBRecorder options object - we will use it to get a video encoder
  string sProfile = pFBRecorder.GetConfigJSONForProfile(FBRecorder.TFBRecorder.TFBRecorderProfiles.SAFE_SCREEN);
  dynamic FBSettings = JsonConvert.DeserializeObject(sProfile);

  // Call the helper function to get the index of the first available video encoder
  var idx = GetFirstAvailableVideoEncoderIndex(pFBRecorder, FBSettings); 

  // And send these encoder parameters to ConvertMP4File, in the ConvertOpts object
  EncoderParams["VideoEncoder"]["Type"] = FBSettings["AvailableVideoEncoders"][idx]["Type"];
  EncoderParams["VideoEncoder"]["Name"] = FBSettings["AvailableVideoEncoders"][idx]["Name"];
  ConvertOpts["VideoEncoderParameters"] = EncoderParams;

  // No ConvertOpts['AudioEncoderParameters'] is defined because we don't want to convert audio, just video 

  // Do the conversion
  return  FBRecorder.TFBRecorder.ConvertMP4File(
    "D:\\original.mp4", // input file
    "D:\\exported.mkv", // output file
    -1, // start at the beginning
    -1, // convert the entire duration
    JsonConvert.SerializeObject(ConvertOpts),
    new FBRecorder.TFBRecorder.Progressor(Progressor)
  );
}

static bool Progressor(long i64Current, long i64Total)
{
  Console.WriteLine(String.Format("{0} of {1}", i64Current, i64Total));
  return true;
}

static int GetFirstAvailableVideoEncoderIndex(TFBRecorder pFBRecorder, dynamic FBSettings)
{
  dynamic jsonVideoEncoders = FBSettings["AvailableVideoEncoders"];
  int i32VideoEncodersCount = jsonVideoEncoders.Count;

  for (int i = 0; i < i32VideoEncodersCount; i++) {
    dynamic jsonVideoEncoder = jsonVideoEncoders[i];
    if (pFBRecorder.CheckVideoEncoderAvailability((int)jsonVideoEncoder["Type"], (string)jsonVideoEncoder["Name"]))
      return i;
  }

  return -1; // No available encoders found
}

Sample code to convert an MP4 to MKV – video and audio.

static bool ConvertExportMKV(TFBRecorder pFBRecorder, bool bVideo, bool bAudio)
{
    // Get a settings object to get the index of video and audio encoders
    string sProfile = pFBRecorder.GetConfigJSONForProfile(FBRecorder.TFBRecorder.TFBRecorderProfiles.SAFE_SCREEN);
    dynamic jsonProfile = JsonConvert.DeserializeObject(sProfile);

    // We will pass the convertSettings object to ConvertMP4File()
    JObject convertSettings = new JObject();
    convertSettings["ExportType"] = (int)FBRecorder.TFBRecorder.TExportType.mkv;

    if (bVideo) {
        // This video settings object will be passed to ConvertMP4File in convertSettings['VideoEncoderParameters']
        JObject Params = new JObject();

        int i32VideoEncoderType = -1; //Unknown = 0, MSMF = 1, NativeIntel = 2, NativeNvidia = 3, NativeAMD = 4
        string sVideoEncoderName = "";

        // Call the helper function to get the index of the first available video encoder
        var idx = GetFirstAvailableVideoEncoderIndex(pFBRecorder, jsonProfile); 
        if (idx != -1) {
          i32VideoEncoderType = FBSettings["AvailableVideoEncoders"][idx]["Type"];
          sVideoEncoderName = FBSettings["AvailableVideoEncoders"][idx]["Name"];
        }

        // Pass the H264 video encoder type and name. This is required when converting to MKV format.
        Params["VideoEncoder"] = new JObject();
        Params["VideoEncoder"]["Type"] = i32VideoEncoderType;
        Params["VideoEncoder"]["Name"] = sVideoEncoderName;

        Params["QualityLevel"] = 80;
        Params["FPS"] = new JObject(); // Set 15fps
        Params["FPS"]["Num"] = 15;
        Params["FPS"]["Den"] = 1;

        // Set the height and width of the converted video. These both default to -1, which keeps the width/height ofthe original video
        Params["Width"] = 640;
        Params["Height"] = 480;

        convertSettings["VideoEncoderParameters"] = Params;
    }

    if (bAudio) {
        // This audio settings object will be passed to ConvertMP4File in convertSettings['AudioEncoderParameters']
        JObject Params = new JObject();
        dynamic AudioEncoders = jsonProfile["AudioSettings"]["AvailableAACEncoders"];

        if (AudioEncoders.Count == 0) {
            Console.WriteLine("Audio encoders are not found");
            return false;
        }

        //use the first available AAC encoder
        Params["Type"] = AudioEncoders[0]["Type"];
        Params["Name"] = AudioEncoders[0]["Name"];

        convertSettings["AudioEncoderParameters"] = Params;

        // 
        // Note - the above code shows how to specify a particular AAC encoder. It can be replaced by:
        // 
        // convertSettings["AudioEncoderParameters"] = new JObject();
        //
        // To use the default AAC encoder.
    }

    string sSettings = JsonConvert.SerializeObject(convertSettings);

    bool bResult = FBRecorder.TFBRecorder.ConvertMP4File(
      "D:\\original.MP4", 
      "D:\\exported.mkv", 
      -1, -1, 
      sSettings, 
      new FBRecorder.TFBRecorder.Progressor(Progressor));

    if (!bResult) {
        Console.WriteLine("ConvertMP4File failed\n");
    }
    else {
        Console.WriteLine("ConvertMP4File succeeded\n");
    }

    return bResult;
}

Sample code to convert an MP4 to AVI – video and audio.

static bool ConvertExportAVI(TFBRecorder pFBRecorder, bool bVideo, bool bAudio)
{
    // Get a settings object to get the index of video and audio encoders
    string sProfile = pFBRecorder.GetConfigJSONForProfile(FBRecorder.TFBRecorder.TFBRecorderProfiles.SAFE_SCREEN);
    dynamic jsonProfile = JsonConvert.DeserializeObject(sProfile);

    // We will pass the convertSettings object to ConvertMP4File()
    JObject convertSettings = new JObject();
    convertSettings["ExportType"] = (int)FBRecorder.TFBRecorder.TExportType.avi;

    if (bVideo) {
        // This video settings object will be passed to ConvertMP4File in convertSettings['VideoEncoderParameters']
        JObject Params = new JObject();

        int i32VideoEncoderType = -1; //Unknown = 0, MSMF = 1, NativeIntel = 2, NativeNvidia = 3, NativeAMD = 4
        string sVideoEncoderName = "";

        // Call the helper function to get the index of the first available video encoder
        var idx = GetFirstAvailableVideoEncoderIndex(pFBRecorder, jsonProfile); 
        if (idx != -1) {
          i32VideoEncoderType = FBSettings["AvailableVideoEncoders"][idx]["Type"];
          sVideoEncoderName = FBSettings["AvailableVideoEncoders"][idx]["Name"];
        }

        // Pass the H264 video encoder type and name. This is required when converting to MKV format.
        Params["VideoEncoder"] = new JObject();
        Params["VideoEncoder"]["Type"] = i32VideoEncoderType;
        Params["VideoEncoder"]["Name"] = sVideoEncoderName;

        Params["QualityLevel"] = 80;
        Params["FPS"] = new JObject(); // Set 15fps
        Params["FPS"]["Num"] = 15;
        Params["FPS"]["Den"] = 1;

        // Set the height and width of the converted video. These both default to -1, which keeps the width/height of the original video
        Params["Width"] = 640;
        Params["Height"] = 480;

        convertSettings["VideoEncoderParameters"] = Params;
    }

    if (bAudio) {
        // AVI uses a default MP3 encoder, so no encoder details need be passed. We pass an empty object for AudioEncoderParameters to specify that audio should be converted.
        JObject Params = new JObject();
        convertSettings["AudioEncoderParameters"] = Params;
    }

    string sSettings = JsonConvert.SerializeObject(convertSettings);

    bool bResult = FBRecorder.TFBRecorder.ConvertMP4File(
      "D:\\original.MP4", 
      "D:\\exported.mkv", 
      -1, -1, 
      sSettings, 
      new FBRecorder.TFBRecorder.Progressor(Progressor));

    if (!bResult) {
        Console.WriteLine("ConvertMP4File failed\n");
    }
    else {
        Console.WriteLine("ConvertMP4File succeeded\n");
    }

    return bResult;
}