FWM Preprocessor SDK Guide

Overview

PallyCon FWM Preprocessor SDK is a C/C++ library that can be ported to an encoding solution. By preprocessing watermark directly in the video encoding process, you can omit the re-encoding process required for CLI Preprocessor.

graph LR;
    subgraph Encoder
    A[Source video] -->|Frame image| B(Preprocessor library)
    B -->|Two set of frame<br>with 0, 1 marked| C["Encoded result<br>(two MP4 videos)"]
    end
    C --> D(DASH or<br>HLS packaging)
    subgraph Packager
    D --> E["Packaging result<br>(two set of streaming content)"]
    end

By default, porting to FFmpeg-based encoder/transcoder is supported. To apply Preprocessor library to other commercial solutions, it is required to port the library by the solution vendor. Please contact us if you need more information or want to apply the library.

Contact Us

Requirements

  • OS: Ubuntu 18.04, 20.04 or CentOS 7
  • Programming language: C/C++
  • FFmpeg development library 3.4.2 or later (sample application only)

Preprecessor API

- iwatermark_t fm_preprocessor_create(FMWatermarkSymbol sym)
  : @return watermark pre-processor instance with 'sym'

- void fm_preprocessor_destroy(iwatermark_t wm)
  : destroys watermark instance

- FMError fm_preprocessor_init(iwatermark_t wm, const char *fmkeyfile, const char *accesskey)
  : initializes watermark with Keyfile and Access-Key
  : @return FMError defined in inkawm.h

- int fm_preprocessor_apply(iwatermark_t wm, FMFrameData *frame)
  : applies watermark
  : @return 0 if successful, otherwise negative integer

- int fm_set_fps(iwatermark_t wm, int framerate_num, int framerate_den, int *target_gop)
  : sets the FPS information of the output video and stores the GOP length according to FPS in target_gop.
  : @return 0 if successful, otherwise negative integer

API Usage

  iwatermark_t wm_0, wm_1

  wm_0 = fm_preprocessor_create(FMWatermarkSymbol_0)
  wm_1 = fm_preprocessor_create(FMWatermarkSymbol_1) [1]
   |
   v
  fm_preprocessor_init(wm_0, "./fwmkeyfile.dat", "FOR_INKA_FORENSIC_WATERMARK_TEST")
  fm_preprocessor_init(wm_1, "./fwmkeyfile.dat", "FOR_INKA_FORENSIC_WATERMARK_TEST") [2]
  or
  fm_preprocessor_init(wm_0, base64(Keyfile), "FOR_INKA_FORENSIC_WATERMARK_TEST")
  fm_preprocessor_init(wm_1, base64(Keyfile), "FOR_INKA_FORENSIC_WATERMARK_TEST")
   |
   v
  fm_set_fps(wm_0, fps_num, fps_den, &target_gop)
  fm_set_fps(wm_1, fps_num, fps_den, &target_gop) [3]
   |
   v
+-------------- loop [4] --------------+
| FrameData frame0                     |
| FrameData frame1                     |
|  |                                   |
|  v                                   |
| fm_preprocessor_apply(wm_0, &frame0) |
| fm_preprocessor_apply(wm_1, &frame1) |
+--------------------------------------+
   |
   v
  fm_preprocessor_destroy(wm_0)
  fm_preprocessor_destroy(wm_1) [5]
  1. Create watermark instance
  • Create a watermark instance to preprocess the 0/1 file.
  • Please Refer to FwmPreprocessSample.cpp::fm_init_watermark()
  1. Initialize the instance and authorize it
  • To use the SDK, you must initialize and authorize instance using Keyfile and Access-Key.
  • The distribution package includes a Keyfile and Access-Key for demonstration. If you use the demo values, Pallycon Demo string appears at the top left of the result video. Please contact our Helpdesk to get a commercial key.
  • Please Refer to FwmPreprocessSample.cpp::fm_init_watermark()
  1. Set FPS information and get GOP length
  • It sets the FPS of the output video to the instance and returns the corresponding GOP length.
  • This only needs to be called once immediately after initialization.
  • This does not affect and/or modify media FPS itself.
  • You must set the returned GOP length in the encoder to ensure that the output video is fixed to this GOP.
  • Please Refer to FwmPreprocessSample.cpp::fmPreprocess()
  1. Apply watermark
  • The SDK uses its own data structures, FrameData, to handle video frame data. Fill the FrameData variables and use them to apply watermark.
  • Please Refer to FwmPreprocessSample.cpp::fm_apply(), inkawm.h
  1. Destroy watermark instance
  • After the watermark operation is finished, the instance must be destroyed.
  • Please Refer to FwmPreprocessSample.cpp::finalize()

Restrictions

The PallyCon Forensic Watermark system must comply with the following restrictions. The detailed setting method is different for each encoder. In the sample application, only cases dealing with FFmpeg and libx264 are described. If you are using libx265/nvenc, see the comments in the sample.

  1. Only the following FPS are acceptable:
  • 23.976, 24, 25, 29.97, 30
  • 47.952, 48, 50, 59.94, 60
  1. GOP must be the value (target_gop) returned by fm_set_fps().
  • AVCodecContext.gop_size = target_gop
    • Please Refer to FwmPreprocessSample.cpp::openOutputFile()
  • "keyint=%d:min-keyint=%d", target_gop, target_gop for x264-params
    • Please Refer to FwmPreprocessSample.cpp::checkAndUpdateParam()
  1. GOP must be closed.
  • open-gop=0 for x264-params
    • Please Refer to FwmPreprocessSample.cpp::checkAndUpdateParam()
  1. Framerate must be fixed.

Sample application

We provide a simple demo source code, key file, and access key to test the SDK using the FFmpeg library.

Cautions

The following instruction installs some C/C++ development tools and FFmpeg dependencies on you system. As this may affect your system, you should be careful if attempting this on an actual service system.

The following instruction has been tested in Docker Ununtu 20.04 containers. It may not work depending on your environments. If some error occur, you must resolve them yourself by referring to the inside of shell script and Makefile or contact us.

Building the sample

After extract the SDK file, please run the following commands in the extracted directory.

$ cd sample/
$ ./install_dependencies.sh
$ make

Running the sample

Run the following command through the built sample executable. The demo key file is named demokey.dat and is distributed with the SDK. The demo access key is the fixed string FOR_INKA_FORENSIC_WATERMARK_TEST.

$ LD_LIBRARY_PATH=./lib ./FwmPreprocessSample your_own_input.mp4 your_own_output.mp4 demokey.dat FOR_INKA_FORENSIC_WATERMARK_TEST
Previous
Next

Last updated on Apr 1, 2024