README

Developer-friendly & type-safe PHP SDK specifically designed to leverage the FastPix platform API.

Introduction

The FastPix PHP SDK simplifies integration with the FastPix platform. This SDK is designed for secure and efficient communication with the FastPix API, enabling easy management of media uploads, live streaming, and simulcasting.

Key Features

FASTPIX API'S: FastPix provides a comprehensive set of APIs that enable developers to manage both on-demand media (video/audio) and live streaming experiences, with built-in security features through cryptographic signing keys. These APIs cover the full lifecycle of content creation, management, distribution, playback, and secure access, making them ideal for building scalable video-first applications.

Media APIs (Video & Audio on Demand)

The Media APIs allow developers to create, retrieve, update, and delete media files, as well as manage metadata, playback settings, and additional tracks such as audio or subtitles. With these endpoints, developers can:

Upload videos directly or create media from URLs. - Manage playback permissions and configure playback IDs. - Add multilingual audio or subtitle tracks for global audiences. - Build robust video-on-demand (VOD) and audio-on-demand (AOD) libraries.
Use case scenarios - Video-on-Demand Platforms: Manage large content libraries for streaming services. - E-Learning Solutions: Upload and organize lecture videos, metadata, and playback settings. - Multilingual Content Delivery: Add multiple language tracks or subtitles to serve global users.

Live Stream APIs

The Live Stream APIs simplify the process of creating, managing, and distributing live content. Developers can initiate broadcasts, configure stream settings, and extend streams to external platforms through simulcasting. These endpoints also support real-time interaction and customization of live events.

Start and manage live broadcasts programmatically. - Control stream metadata, privacy, and playback options. - Simulcast to platforms like YouTube, Facebook, or Twitch. - Update stream details and manage live playback IDs in real time.
Use case scenarios - Event Broadcasting: Enable organizers to set up live streams for conferences, concerts, or webinars. - Creator Platforms: Provide streamers with tools for broadcasting gameplay, tutorials, or vlogs with simulcasting support. - Corporate Streaming: Deliver secure internal town halls or meetings with privacy and playback controls.

Video Data APIs

The Video Data APIs Provide insights into viewer interactions, performance metrics, and playback errors to optimize content delivery and user experience.

Track video views, unique viewers, and engagement metrics
Identify top-performing content and usage patterns
Break down data by browser, device, or geography
Detect playback errors and performance issues
Enable data-driven content strategy decisions

Use case scenarios

Analytics Dashboards: Monitor performance across content libraries
Quality Monitoring: Diagnose and resolve playback issues
Content Strategy Optimization: Identify high-value content
User Behavior Insights: Understand audience interactions

Signing Keys

FastPix also provides endpoints for managing cryptographic signing keys, which are essential for securely signing and verifying tokens, such as JSON Web Tokens (JWTs). These keys are critical for authenticating and authorizing API requests, as well as for protecting access to media assets.

Private key: Used to create digital signatures (kept secret). - Public key: Used to verify digital signatures (shared for verification).
By rotating and managing signing keys regularly, developers can maintain strong security practices and prevent unauthorized access.
Use case scenarios - Token-based authentication: Validate user access to premium or subscription-based content. - Key rotation: Regularly rotate keys to reduce risk of compromise. - Protect intellectual property: Prevent unauthorized distribution of valuable media assets. - Control usage: Restrict access to specific users, groups, or contexts. - Prevent tampering: Ensure requested assets have not been modified. - Time-bound access: Enable signed URLs with expiration for controlled viewing windows.

Prerequisites:

PHP 7.4 or later
Composer package manager
FastPix API credentials (Access Token and Secret Key)

fastpix/sdk

SDK Installation

Tip

To finish publishing your SDK you must run your first generation action.

The SDK relies on Composer to manage its dependencies.

To install the SDK first add the below to your composer.json file:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/FastPix/fastpix-php.git"
        }
    ],
    "require": {
        "fastpix/sdk": "*"
    }
}

Then run the following command:

composer update

Initialization

You can set the security parameters through the security builder method when initializing the SDK client instance. For example:

declare(strict_types=1);

require 'vendor/autoload.php';

use FastPix\Sdk;
use FastPix\Sdk\Models\Components;

$sdk = SDK::builder()
    ->setSecurity(
        new Components\Security(
            username: 'your-access-token',
            password: 'your-secret-key',
        )
    )
    ->build();

SDK Example Usage

Example

declare(strict_types=1);

require 'vendor/autoload.php';

use FastPix\Sdk;
use FastPix\Sdk\Models\Components;

$sdk = SDK::builder()
    ->setSecurity(
        new Components\Security(
            username: 'your-access-token',
            password: 'your-secret-key',
        )
    )
    ->build();

$request = new Components\CreateMediaRequest(
    inputs: [
        new Components\VideoInput(
            type: 'video',
            url: 'https://static.fastpix.io/sample.mp4',
        ),
    ],
    metadata: [
        'key1' => 'value1',
    ],
    accessPolicy: Components\CreateMediaRequestAccessPolicy::Public,
);

$response = $sdk->inputVideo->createMedia(
    request: $request
);

if ($response->createMediaSuccessResponse !== null) {
    // handle response
}

Available Resources and Operations

Available methods

dimensions

listDimensions - List the dimensions
getDimensionsData - Get dimensions data

drmConfigurations

getDrmConfiguration - Get list of DRM configuration IDs
getDrmConfigurationById - Get DRM configuration by ID

errors

getErrorData - Get error data

inputVideo

createMedia - Create media from URL
directUpload - Upload media from device

inVideoAIFeatures

updateMediaSummary - Generate video summary
updateMediaChapters - Generate video chapters
updateMediaNamedEntities - Generate named entities
updateMediaModeration - Enable video moderation

livePlayback

createPlaybackIdOfStream - Create a playbackId
deletePlaybackIdOfStream - Delete a playbackId
getLiveStreamPlaybackId - Get playbackId details

manageLiveStream

getAllStreams - Get all live streams
getLiveStreamViewerCountById - Get stream views by ID
getLiveStreamById - Get stream by ID
deleteLiveStream - Delete a stream
updateLiveStream - Update a stream
enableLiveStream - Enable a stream
disableLiveStream - Disable a stream
completeLiveStream - Complete a stream

manageVideos

listMedia - Get list of all media
listLiveClips - Get all clips of a live stream
getMedia - Get a media by ID
updatedMedia - Update a media by ID
deleteMedia - Delete a media by ID
addMediaTrack - Add audio / subtitle track
cancelUpload - Cancel ongoing upload
updateMediaTrack - Update audio / subtitle track
deleteMediaTrack - Delete audio / subtitle track
generateSubtitleTrack - Generate track subtitle
updatedSourceAccess - Update the source access of a media by ID
updatedMp4Support - Update the mp4Support of a media by ID
retrieveMediaInputInfo - Get info of media inputs
listUploads - Get all unused upload URLs
getMediaClips - Get all clips of a media
updateMediaSummary - Update media summary
updateMediaChapters - Update media chapters
updateMediaNamedEntities - Update named entities
updateMediaModeration - Update moderation settings

metrics

getMetricsBreakdown - Get metrics breakdown
getVideoMetrics - Get overall video metrics
getMetricsTimeseries - Get metrics timeseries
getMetricsComparison - Get metrics comparison

playback

createMediaPlaybackId - Create a playback ID
deleteMediaPlaybackId - Delete a playback ID
getPlaybackId - Get a playback ID

playlist

createAPlaylist - Create a new playlist
getAllPlaylists - Get all playlists
getPlaylistById - Get a playlist by ID
updateAPlaylist - Update a playlist by ID
deleteAPlaylist - Delete a playlist by ID
addMediaToPlaylist - Add media to a playlist by ID
replacePlaylistMedia - Replace playlist media
changeMediaOrderInPlaylist - Change media order in a playlist by ID
deleteMediaFromPlaylist - Delete media in a playlist by ID

signingKeys

createSigningKey - Create a signing key
getAllSigningKeys - Get list of signing key
deleteSigningKey - Delete a signing key
getSigningKeyById - Get signing key by ID

simulcastStream

createSimulcastOfStream - Create a simulcast
listSimulcastsOfStream - List simulcast targets
deleteSimulcastOfStream - Delete a simulcast
getSpecificSimulcastOfStream - Get a specific simulcast
updateSpecificSimulcastOfStream - Update a simulcast

startLiveStream

createNewStream - Create a new stream
getStreamById - Get stream by ID
updateStream - Update stream

views

getViewsData - Get views data
getViewsByDimension - Get views by dimension
getViewsByTopContent - Get top content views
getTimeseriesViews - Get concurrent viewers timeseries
getViewsCount - Get views count

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide an Options object built with a RetryConfig object to the call:

declare(strict_types=1);

require 'vendor/autoload.php';

use FastPix\Sdk;
use FastPix\Sdk\Models\Components;
use FastPix\Sdk\Utils\Retry;

$sdk = SDK::builder()
    ->setSecurity(
        new Components\Security(
            username: 'your-access-token',
            password: 'your-secret-key',
        )
    )
    ->build();

$request = new Components\CreateMediaRequest(
    inputs: [
        new Components\VideoInput(
            type: 'video',
            url: 'https://static.fastpix.io/sample.mp4',
        ),
    ],
    metadata: [
        'key1' => 'value1',
    ],
    accessPolicy: Components\CreateMediaRequestAccessPolicy::Public,
);

$response = $sdk->inputVideo->createMedia(
    request: $request,
    options: Utils\Options->builder()->setRetryConfig(
        new Retry\RetryConfigBackoff(
            initialIntervalMs: 1000,
            maxIntervalMs: 50000,
            exponent: 1.1,
            maxElapsedTimeMs: 100000,
            retryConnectionErrors: false,
        ))->build()
);

if ($response->createMediaSuccessResponse !== null) {
    // handle response
}

If you'd like to override the default retry strategy for all operations that support retries, you can pass a RetryConfig object to the SDKBuilder->setRetryConfig function when initializing the SDK:

declare(strict_types=1);

require 'vendor/autoload.php';

use FastPix\Sdk;
use FastPix\Sdk\Models\Components;
use FastPix\Sdk\Utils\Retry;

$sdk = SDK::builder()
    ->setRetryConfig(
        new Retry\RetryConfigBackoff(
            initialIntervalMs: 1000,
            maxIntervalMs: 50000,
            exponent: 1.1,
            maxElapsedTimeMs: 100000,
            retryConnectionErrors: false,
        )
  )
    ->setSecurity(
        new Components\Security(
            username: 'your-access-token',
            password: 'your-secret-key',
        )
    )
    ->build();

$request = new Components\CreateMediaRequest(
    inputs: [
        new Components\VideoInput(
            type: 'video',
            url: 'https://static.fastpix.io/sample.mp4',
        ),
    ],
    metadata: [
        'key1' => 'value1',
    ],
    accessPolicy: Components\CreateMediaRequestAccessPolicy::Public,
);

$response = $sdk->inputVideo->createMedia(
    request: $request
);

if ($response->createMediaSuccessResponse !== null) {
    // handle response
}

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or throw an exception.

By default an API error will raise a Errors\APIException exception, which has the following properties:

Property	Type	Description
`$message`	string	The error message
`$statusCode`	int	The HTTP status code
`$rawResponse`	?\Psr\Http\Message\ResponseInterface	The raw HTTP response
`$body`	string	The response content

When custom error responses are specified for an operation, the SDK may also throw their associated exception. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the createMedia method throws the following exceptions:

Error Type	Status Code	Content Type
Errors\BadRequestException	400	application/json
Errors\InvalidPermissionException	401	application/json
Errors\ForbiddenException	403	application/json
Errors\ValidationErrorResponse	422	application/json
Errors\APIException	4XX, 5XX	/

Example

declare(strict_types=1);

require 'vendor/autoload.php';

use FastPix\Sdk;
use FastPix\Sdk\Models\Components;
use FastPix\Sdk\Models\Errors;

$sdk = SDK::builder()
    ->setSecurity(
        new Components\Security(
            username: 'your-access-token',
            password: 'your-secret-key',
        )
    )
    ->build();

try {
    $request = new Components\CreateMediaRequest(
        inputs: [
            new Components\VideoInput(
                type: 'video',
                url: 'https://static.fastpix.io/sample.mp4',
            ),
        ],
        metadata: [
            'key1' => 'value1',
        ],
        accessPolicy: Components\CreateMediaRequestAccessPolicy::Public,
    );

    $response = $sdk->inputVideo->createMedia(
        request: $request
    );

    if ($response->createMediaSuccessResponse !== null) {
        // handle response
    }
} catch (Errors\BadRequestExceptionThrowable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\InvalidPermissionExceptionThrowable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\ForbiddenExceptionThrowable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\ValidationErrorResponseThrowable $e) {
    // handle $e->$container data
    throw $e;
} catch (Errors\APIException $e) {
    // handle default exception
    throw $e;
}

Server Selection

Override Server URL Per-Client

The default server can be overridden globally using the setServerUrl(string $serverUrl) builder method when initializing the SDK client instance. For example:

declare(strict_types=1);

require 'vendor/autoload.php';

use FastPix\Sdk;
use FastPix\Sdk\Models\Components;

$sdk = SDK::builder()
    ->setServerURL('https://api.fastpix.io/v1/')
    ->setSecurity(
        new Components\Security(
            username: 'your-access-token',
            password: 'your-secret-key',
        )
    )
    ->build();

$request = new Components\CreateMediaRequest(
    inputs: [
        new Components\VideoInput(
            type: 'video',
            url: 'https://static.fastpix.io/sample.mp4',
        ),
    ],
    metadata: [
        'key1' => 'value1',
    ],
    accessPolicy: Components\CreateMediaRequestAccessPolicy::Public,
);

$response = $sdk->inputVideo->createMedia(
    request: $request
);

if ($response->createMediaSuccessResponse !== null) {
    // handle response
}

Detailed Usage

For a complete understanding of each API's functionality, including request and response details, parameter descriptions, and additional examples, please refer to the FastPix API Reference.

The API reference provides comprehensive documentation for all available endpoints and features, ensuring developers can integrate and utilize FastPix APIs efficiently.

fastpix / sdk

Maintainers

Details

README

Introduction

Key Features

Media APIs (Video & Audio on Demand)

Live Stream APIs

Video Data APIs

Signing Keys

Prerequisites:

Table of Contents

SDK Installation

Initialization

SDK Example Usage

Example

Available Resources and Operations

dimensions

drmConfigurations

errors

inputVideo

inVideoAIFeatures

livePlayback

manageLiveStream

manageVideos

metrics

playback

playlist

signingKeys

simulcastStream

startLiveStream

views

Retries

Error Handling

Example

Server Selection

Override Server URL Per-Client

Detailed Usage