safestream/safestream-php-sdk

PHP SDK for SafeStream: On Demand Video Watermarking

1.2.5 2017-04-14 18:47 UTC

Requires

• guzzlehttp/guzzle: ^6.2

Requires (Dev)

• phpunit/phpunit: ^4.8

MIT

• Mike Delano

README

Installing the SafeStream SDK

The recommended way to install the SDK is through Composer.

# Install Composer
curl -sS https://getcomposer.org/installer | php

Next, run the Composer command to install the latest stable version of Guzzle:

composer.phar require safestream/safestream-php-sdk

After installing, you need to require Composer's autoloader:

require 'vendor/autoload.php';

You can then later update the SDK using composer:

composer.phar update

Getting Started

SafeStreamClient

First, you'll need to instantiate a new SafeStreamClient. Through the client, you can access all of SafeStream's functionality. Creating the client is simple.

$safeStreamClient = new \SafeStream\SafeStreamClient(["apiKey" => "YOUR API KEY", "clientId" => "YOUR CLIENT ID"]);

Some of our API integrations span multiple accounts. The SafeStream API allows a single API key pair to access multiple accounts through the domain ID. If you have multiple accounts you can create the SafeStream client with the domain ID. This way all requests that you make will be within the context of the account you intend them to be. Here's how:

$safeStreamClient = new \SafeStream\SafeStreamClient(["apiKey" => "YOUR API KEY", "clientId" => "YOUR CLIENT ID", "domainId" => "YOUR DOMAIN ID"]);

Videos

Before SafeStream can watermark your videos you first need create them. When you create a video in SafeStream your video gets downloaded and encoded so it is ready for your future watermarking requests. Creating a video typically takes half of real time. Meaning that a 5 minute video would take 2-3 minutes.

#####Functions ######create(Video $video, $waitForIngest = 0)

######createFromSourceUrl($sourceUrl, $waitForIngest = 0)

######find($svideoKey)

Examples

Here's a simple example of creating a video:

$safeStreamClient.video().createFromSourceUrl("https://example.com/my-video.mp4");

You can also give your video's custom keys to make it easier to find them later. For example, if you have a video in your own system that you've named "red-carpet-reel-20" you can give SafeStream this key and will store it with the video. This way, you don't have to store SafeStream id's if you don't want to.

Here's a simple example of creating a video with a custom key:

$safeStreamClient.video().create(["sourceUrl" => "https://example.com/my-video.mp4", "key" => "red-carpet-reel-20"]);

Watermarking Videos

Functions

create($videoKey, $watermarkConfiguration, $timeout = 90000)

createFromTemplate($videoKey, $templateId, $templateMapping, $timeout = 90000)

Examples

Basic Watermark

$watermarkConfiguration = new \SafeStream\Watermark\WatermarkConfiguration(["content" => "YOUR NAME"]);
$safeStreamClient->watermark()->create("YOUR VIDEO KEY", $watermarkConfiguration, 90000);

Watermarking Videos from a Template

Instead of passing in the watermark configuration each time you watermark a video you can use templates. Templates are stored watermark configuration with varible text in the content field. See blah for more on creating templates.

$watermarkConfiguration = new \SafeStream\Watermark\WatermarkConfiguration(["content" => "YOUR NAME"]);
$safeStreamClient->watermark()->createFromTemplate("YOUR VIDEO KEY", "TEMPLATE ID", array("first_name", "Joe"));

The above example assumes you have a template with a variable place holder, "first_name" which might look something like:

 {
  "settings": [
    {
      "content": "First Name [%first_name%]",
      "horizontalAlignment": "CENTER",
      "verticalAlignment": "MIDDLE",
      "fontColor": "0xffffff",
      "shadowOpacity": 0.1,
      "fontOpacity": 0.3,
      "type": "TEXT",
      "shadowOffsetX": 0.08,
      "fontSize": 0.05,
      "shadowColor": "0x000000",
      "y": 0.5,
      "x": 0.5,
      "shadowOffsetY": 0.08
    }
  ]
}

Watermark Configuration Properties

Animation

Text and image watermarks can be animated to move from one coordinate to another. Adding movement to your watermark is simple. You specify the start and end positions as well as the start and end times for the animation to take place and your done.

Examples

Moving a text watermark from left to right

$watermarkConfiguration = new \SafeStream\Watermark\WatermarkConfiguration();
$watermarkConfiguration
    .withContent("YOUR NAME")
    .withX(0.0)
    .withY(0.0)
    .move(1, 0, 0, 20);

$safeStreamClient->watermark()->create("YOUR VIDEO KEY", $watermarkConfiguration, 90000);

The above example will move the text "YOUR NAME" across the top of the video over a period of 20 seconds. Breaking the move function call down, it will move the text to the x coordiate, 1, and will make no movement along the y axis. It will start at 0 seconds and move to 20 seconds move(1, 2, 2, 20)

Animation Configuration Properties

Watermarking Templates

Watermarking templates allow you to store pre-configured watermark settings in SafeStream. This allows you to avoid having to send watermark configurations with each watermarking request. The Templates allow you to set all of the watermark configuration properties but also allow you to set the content field to contain variable content which would be hydrated during subsequent watermark requests.

Functions

save(Template $template)

Examples

Creating a new watermarking template:

$watermarkConfiguration = new \SafeStream\Watermark\WatermarkConfiguration(["content" => "[%first_name%]"]);
$template = new \SafeStream\Watermark\Template\Template();
$template->addWatermarkConfiguration($watermarkConfiguration);
$safeStreamClient->watermark()->template()->save($template);

And then to use if for watermarking:

$watermarkClient->watermark()->createFromTemplate("YOUR VIDEO KEY", "YOUR TEMPLATE ID", array("first_name" => "Joe"));

Example PHP page

<?php

// Require autoload which is installed via composer
require 'vendor/autoload.php';

// Variables should be set in the middle tier so that a user can not modify them client side
$name = "Sample User";
$email = "[e-mail]";
$company = "Acme Studios 22";

// Instantiate the SafeStreamClient using your own API Key
$safeStreamClient = new \SafeStream\SafeStreamClient(["protocol" => "https", "hostName" => "api.safestream.com", "apiKey" => "XXXX"]);

// Configuration for the Name
$watermarkConfiguration1 = new \SafeStream\Watermark\WatermarkConfiguration([
    "content" => "Licensed to " . $name,
    "fontColor" => "FFFFFF",
    "y" => 0.83,
    "x" => 0.03,
    "fontOpacity" => 0.5,
    "fontSize" => 0.03,
    "horizontalAlignment" => "LEFT",
    "verticalAlignment"  => "TOP"
]);

// Configuration for the Company
$watermarkConfiguration2 = new \SafeStream\Watermark\WatermarkConfiguration([
    "content" => $company,
    "fontColor" => "FFFFFF",
    "y" =>   0.04,
    "x" =>  0.97,
    "fontOpacity" => 0.5,
    "fontSize" => 0.03,
    "horizontalAlignment" => "RIGHT",
    "verticalAlignment"  => "TOP",
    "shadowColor"  => "000000",
    "shadowOffsetX"  => 0.08,
    "shadowOffsetY" => 0.08,
    "shadowOpacity" => 0.33
]);

 $mydata = $safeStreamClient -> watermark()->create("feature-1",array($watermarkConfiguration1,$watermarkConfiguration2),0);
 
 // Return the request to the browser
 echo json_encode($mydata);

}

?>

Tests

export SAFESTREAM_CLIENT_ID=YOUR_CLIENT_ID
export SAFESTREAM_API_KEY=YOUR_API_KEY
phpunit tests/SafeStreamClientTests.php 

License