Java SDK

The FastPix Java SDK provides a powerful, developer-friendly way to build video capabilities into your Java applications. You get support for media uploads, live streaming, simulcasting, and playback management and more, so you can build sophisticated video-based applications for your use case.

Prerequisites

Step 1: Installation

Step 2: Importing the SDK

Step 3: Initialization

Perform media operations

Live stream operations

Error handling

Support & resource

Prerequisites

Before you start using the SDK, make sure you have the following:

JDK 11 or later: This SDK is compatible with Java 11 or higher
Maven or Gradle: Required for dependency management
IDE: IntelliJ IDEA, Eclipse, or VS Code with Java extensions
FastPix API credentials: You’ll need an Access Token and a Secret Key. You can generate these credentials by following the steps in the Authentication guide
Basic understanding of Java and REST APIs: Familiarity with Java development and API integration concepts

Step 1: Installation

The SDK is available through Maven Central and can be installed using your preferred build tool.

Using Maven

Add this to your pom.xml file:

<dependency> 
    <groupId>io.fastpix</groupId> 
    <artifactId>sdk</artifactId> 
    <version>0.1.0</version> 
</dependency>

Using Gradle

Add this to your build.gradle file:

implementation 'io.fastpix:sdk:0.1.0'

Using Gradle (Kotlin DSL)

Add this to your build.gradle.kts file:

implementation("io.fastpix:sdk:0.1.0")

Building from Source

If you want to build the SDK from source:

# Clone the repository

git clone [https://github.com/FastPix/fastpix-java.git](https://github.com/FastPix/fastpix-java.git)\
cd fastpix-java

# Build the SDK

./gradlew build

# Install to local Maven repository

./gradlew publishToMavenLocal -Pskip.signing

Step 2: Import the SDK

Add the necessary import statements to your Java files:

import io.fastpix.sdk.FastPixSDK;  &#x20;
import io.fastpix.sdk.models.components.\*;&#x20;
import io.fastpix.sdk.models.errors.\*;&#x20;
import io.fastpix.sdk.models.operations.\*;&#x20;
import java.util.Optional;&#x20;
import java.util.List;&#x20;

Step 3: Initialization

You can set the security parameters through the builder when initializing the SDK client instance. The SDK uses different server URLs for different operations:

For Media Operations

Use the base FastPix server URL:

FastPixSDK fastPix = FastPixSDK.builder() 
    .security(Security.builder() 
        .username("your-access-token-id") 
        .password("your-secret-key") 
        .build()) 
    .serverURL("https://api.fastpix.io/v1/") 
    .build();

For Live Stream Operations

Use the live streaming specific server URL:

FastPixSDK fastPix = FastPixSDK.builder() 
    .security(Security.builder() 
        .username("your-access-token-id") 
        .password("your-secret-key") 
        .build()) 
    .serverURL("https://api.fastpix.io/v1/live-stream") 
    .build();

Environment Variables (Recommended)

For production applications, use environment variables to keep secrets out of your codebase as a security approach:

String accessToken = System.getenv("FASTPIX_ACCESS_TOKEN"); 
String secretKey = System.getenv("FASTPIX_SECRET_KEY"); 
 
FastPixSDK fastPix = FastPixSDK.builder() 
    .security(Security.builder() 
        .username(accessToken) 
        .password(secretKey) 
        .build()) 
    .serverURL("https://v1.fastpix.io") // or 'https://v1.fastpix.io/live' for live streams 
    .build();

Perform Media Operations

1.1 Create Media from URL

This endpoint allows developers or users to create a new video or audio media in FastPix using a publicly accessible URL. FastPix will fetch the media from the provided URL, process it, and store it on the platform for use.

Use the createMedia() method to create media from a URL. This is useful when you want to import videos from external sources.

For more details refer to Create Media From URL API documentation.

// Initialize SDK for media operations 
FastPixSDK fastPix = FastPixSDK.builder() 
    .security(Security.builder() 
        .username("your-access-token-id") 
        .password("your-secret-key") 
        .build()) 
    .serverURL("https://api.fastpix.io/v1/on-demand") 
    .build(); 
 
// Create media from URL 
CreateMediaRequest request = CreateMediaRequest.builder() 
    .inputs(List.of( 
        Input.builder() 
            .videoInput(VideoInput.builder() 
                .type("video") 
                .url("https://example.com/video.mp4") 
                .startTime(0.0) 
                .endTime(60.0) 
                .build()) 
            .build() 
    )) 
    .metadata(CreateMediaRequestMetadata.builder() 
        .title("My Video Title") 
        .description("Video description here") 
        .build()) 
    .accessPolicy(CreateMediaRequestAccessPolicy.PUBLIC) 
    .mp4Support(CreateMediaRequestMp4Support.CAPPED_4K) 
    .build(); 
 
CreateMediaResponse response = fastPix.inputVideo().createMedia() 
    .request(Optional.of(request)) 
    .call(); 
 
if (response.createMediaResponseBody().isPresent()) { 
    System.out.println("Media created successfully!"); 
    System.out.println("Media ID: " + response.createMediaResponseBody().get().data().id()); 
    System.out.println("Status: " + response.createMediaResponseBody().get().data().status()); 
}

1.2 Upload Media from Device

This endpoint enables you to upload a video file directly from your local device to FastPix for processing and storage. When you invoke this API with your preferred media settings, the response returns an uploadId and a pre-signed URL, providing a streamlined experience for uploading.

Use the directUploadVideoMedia() method to upload media directly from a device or file system.

For more details refer to Upload Media From Device API documentation.

// Upload media directly from device 
DirectUploadVideoMediaRequest request = DirectUploadVideoMediaRequest.builder() 
    .corsOrigin("*") 
    .pushMediaSettings(PushMediaSettings.builder() 
        .accessPolicy(DirectUploadVideoMediaAccessPolicy.PUBLIC) 
        .startTime(0.0) 
        .endTime(60.0) 
        .build()) 
    .build(); 
 
DirectUploadVideoMediaResponse response = fastPix.inputVideo().directUploadVideoMedia() 
    .request(Optional.of(request)) 
    .call(); 
 
if (response.directUploadVideoMediaResponseBody().isPresent()) { 
    System.out.println("Media uploaded successfully!"); 
    System.out.println("Upload ID: " + response.directUploadVideoMediaResponseBody().get().data().uploadId()); 
    System.out.println("Upload URL: " + response.directUploadVideoMediaResponseBody().get().data().uploadUrl()); 
}

1.3 List All Media

This endpoint returns a list of all media files created from a URL or uploaded as file objects within your organization. Each media entry contains metadata such as the media ID, creation date, status, and type. It allows you to retrieve a comprehensive overview of your media assets, making it easier to manage and review them.

Use the listMedia() method to retrieve a list of all media files in your account.

For more details refer to List All Media API documentation.

ListMediaResponse response = fastPix.manageVideos().listMedia() 
    .limit(Optional.of(20L)) 
    .offset(Optional.of(1L)) 
    .orderBy(Optional.of(ListMediaOrderBy.DESC)) 
    .call(); 
 
if (response.listMediaResponseBody().isPresent()) { 
    List<Media> mediaList = response.listMediaResponseBody().get().data(); 
    for (Media media : mediaList) { 
        System.out.println("Media ID: " + media.id()); 
        System.out.println("Title: " + media.title()); 
        System.out.println("Status: " + media.status()); 
        System.out.println("Duration: " + media.duration()); 
    } 
}

1.4 Get Media by ID

By calling this endpoint, you can retrieve detailed information about a specific media item, including its current status and a playbackId. This is particularly useful for retrieving specific media details when managing large content libraries.

Use the getMedia() method to retrieve details of a specific media file using its media ID.

For more details refer to Get Media by ID API documentation.

String mediaId = "your-media-id"; 
GetMediaResponse response = fastPix.manageVideos().getMedia(mediaId); 
 
if (response.getMediaResponseBody().isPresent()) { 
    Media media = response.getMediaResponseBody().get().data(); 
    System.out.println("Title: " + media.title()); 
    System.out.println("Duration: " + media.duration()); 
    System.out.println("Status: " + media.status()); 
    System.out.println("Created At: " + media.createdAt()); 
}

1.5 Update Media

This endpoint allows you to update specific parameters of an existing media file. You can modify the key-value pairs of the metadata that were provided in the payload during the creation of media from a URL or when uploading the media as a file object.

Use the updatedMedia() method to update metadata or settings for a specific media file.

For more details refer to Update Media API documentation.

String mediaId = "your-media-id"; 
UpdatedMediaRequestBody requestBody = UpdatedMediaRequestBody.builder() 
    .metadata(Map.of( 
        "title", "Updated Title", 
        "description", "Updated description" 
    )) 
    .build(); 
 
UpdatedMediaResponse response = fastPix.manageVideos().updatedMedia(mediaId, Optional.of(requestBody)); 
 
if (response.updatedMediaResponseBody().isPresent()) { 
    System.out.println("Media updated successfully!"); 
}

1.6 Delete Media

This endpoint allows you to permanently delete a specific video or audio media file along with all associated data. If you wish to remove a media file from FastPix storage, use this endpoint with the mediaId (either uploadId or id) received during the media’s creation or upload.

Use the deleteMedia() method to remove a media file from your account.

For more details refer to Delete Media API documentation.

String mediaId = "your-media-id"; 
fastPix.manageVideos().deleteMedia(mediaId); 
 
System.out.println("Media deleted successfully!");

1.7 Create Media Playback ID

You can create a new playback ID for a specific media asset. If you have already retrieved an existing playbackId using the “Get Media by ID” endpoint for a media asset, you can use this endpoint to generate a new playback ID with a specified access policy.

Use the createMediaPlaybackId() method to generate a playback ID for a media file.

For more details refer to Create Media Playback ID API documentation.

String mediaId = "your-media-id"; 
CreateMediaPlaybackIdRequestBody requestBody = CreateMediaPlaybackIdRequestBody.builder() 
    .accessPolicy(CreateMediaPlaybackIdAccessPolicy.PUBLIC) 
    .build(); 
 
CreateMediaPlaybackIdResponse response = fastPix.playback().createMediaPlaybackId(mediaId, requestBody); 
 
if (response.createMediaPlaybackIdResponseBody().isPresent()) { 
    System.out.println("Playback ID: " + response.createMediaPlaybackIdResponseBody().get().data().id()); 
    System.out.println("Playback URL: https://stream.fastpix.io/" +  
                      response.createMediaPlaybackIdResponseBody().get().data().id() + ".m3u8"); 
}

1.8 Delete Media Playback ID

This endpoint allows you to remove a specific playback ID associated with a media asset. Deleting a playbackId will revoke access to the media content linked to that ID.

Use the deleteMediaPlaybackId() method to remove a playback ID for a media file.

For more details refer to Delete Media Playback ID API documentation.

String mediaId = "your-media-id"; 
String playbackId = "your-playback-id"; 
 
fastPix.playback().deleteMediaPlaybackId(mediaId, playbackId); 
 
System.out.println("Playback ID deleted successfully!");

Live Stream Operations

2.1 Create Live Stream

This endpoint allows you to create a new live stream with specified settings. You can configure various parameters such as the stream key, recording settings, and playback options to customize the live streaming experience according to your requirements.

Use the createNewStream() method to create a new live stream with your desired configuration.

For more details refer to Create Live Stream API documentation.

// Initialize SDK for live stream operations 
FastPixSDK fastPix = FastPixSDK.builder() 
    .security(Security.builder() 
        .username("your-access-token-id") 
        .password("your-secret-key") 
        .build()) 
    .serverURL("https://api.fastpix.io/v1/live-stream") 
    .build(); 
 
// Create a new live stream 
CreateLiveStreamRequest request = CreateLiveStreamRequest.builder() 
    .metadata(CreateLiveStreamRequestMetadata.builder() 
        .title("My Live Stream") 
        .description("This is my live stream description") 
        .build()) 
    .reconnectWindow(60) // 60 seconds 
    .accessPolicy(CreateLiveStreamRequestAccessPolicy.PUBLIC) 
    .dvr(true) // Enable DVR mode 
    .build(); 
 
CreateNewStreamResponse response = fastPix.startLiveStream().createNewStream() 
    .request(Optional.of(request)) 
    .call(); 
 
if (response.liveStreamResponseDTO().isPresent()) { 
    System.out.println("Live stream created successfully!"); 
    System.out.println("Stream ID: " + response.liveStreamResponseDTO().get().data().streamId()); 
    System.out.println("Stream Key: " + response.liveStreamResponseDTO().get().data().streamKey()); 
    System.out.println("RTMP URL: " + response.liveStreamResponseDTO().get().data().rtmpUrl()); 
}

2.2 List All Live Streams

This endpoint returns a comprehensive list of all live streams within your organization. It provides detailed information about each stream, including their current status, creation date, and configuration settings, making it easy to manage and monitor your live streaming activities.

Use the getAllStreams() method to retrieve a list of all live streams in your account.

For more details refer to List All Live Streams API documentation.

GetAllStreamsResponse response = fastPix.manageLiveStream().getAllStreams() 
    .limit(Optional.of("20")) 
    .offset(Optional.of("1")) 
    .orderBy(Optional.of(GetAllStreamsOrderBy.DESC)) 
    .call(); 
 
if (response.getStreamsResponse().isPresent()) { 
    List<LiveStreamResponseDTO> streams = response.getStreamsResponse().get().data(); 
    for (LiveStreamResponseDTO stream : streams) { 
        System.out.println("Stream ID: " + stream.streamId()); 
        System.out.println("Title: " + stream.title()); 
        System.out.println("Status: " + stream.status()); 
        System.out.println("Created At: " + stream.createdAt()); 
    } 
}

2.3 Get Live Stream by ID

This endpoint allows you to retrieve detailed information about a specific live stream using its unique identifier. It returns comprehensive data including the stream’s current status, configuration settings, and associated metadata, providing you with complete visibility into the stream’s properties and state.

Use the getLiveStreamById() method to retrieve details of a specific live stream using its stream ID.

For more details refer to Get Live Stream by ID API documentation.

String streamId = "your-stream-id"; 
GetLiveStreamByIdResponse response = fastPix.manageLiveStream().getLiveStreamById(streamId); 
 
if (response.livestreamgetResponse().isPresent()) { 
    LiveStreamResponseDTO stream = response.livestreamgetResponse().get().data(); 
    System.out.println("Title: " + stream.title()); 
    System.out.println("Status: " + stream.status()); 
    System.out.println("Stream Key: " + stream.streamKey()); 
    System.out.println("RTMP URL: " + stream.rtmpUrl()); 
}

2.4 Update Live Stream

This endpoint enables you to modify the configuration and settings of an existing live stream. You can update various parameters such as the stream name, recording preferences, and other configuration options to adapt the stream to changing requirements or preferences.

Use the updateLiveStream() method to update settings for a specific live stream.

For more details refer to Update Live Stream API documentation.

String streamId = "your-stream-id"; 
PatchLiveStreamRequest request = PatchLiveStreamRequest.builder() 
    .metadata(PatchLiveStreamRequestMetadata.builder() 
        .title("Updated Stream Name") 
        .description("Updated stream description") 
        .build()) 
    .build(); 
 
UpdateLiveStreamResponse response = fastPix.manageLiveStream().updateLiveStream(streamId, request); 
 
if (response.updateLiveStreamResponse().isPresent()) { 
    System.out.println("Live stream updated successfully!"); 
}

2.5 Delete Live Stream

This endpoint allows you to permanently remove a specific live stream and all its associated data from the FastPix platform. When you delete a live stream, it will be completely removed from your account, including any recordings or metadata associated with it.

Use the deleteLiveStream() method to remove a live stream from your account.

For more details refer to Delete Live Stream API documentation.

 String streamId = "your-stream-id"; 
fastPix.manageLiveStream().deleteLiveStream(streamId); 
 
System.out.println("Live stream deleted successfully!");

2.6 Create Live Stream Playback ID

This endpoint enables you to generate a new playback ID for a specific live stream. The playback ID provides a secure and controlled way to access the live stream content, allowing you to implement custom access policies and restrictions for your live streaming content.

Use the createPlaybackIdOfStream() method to generate a playback ID for a live stream.

For more details refer to Create Live Stream Playback ID API documentation.

String streamId = "your-stream-id"; 
PlaybackIdRequest request = PlaybackIdRequest.builder() 
    .accessPolicy(PlaybackIdRequestAccessPolicy.PUBLIC) 
    .build(); 
 
CreatePlaybackIdOfStreamResponse response = fastPix.playback().createPlaybackIdOfStream(streamId, request); 
 
if (response.playbackIdResponse().isPresent()) { 
    System.out.println("Playback ID: " + response.playbackIdResponse().get().data().id()); 
    System.out.println("Playback URL: https://stream.fastpix.io/" +  
                      response.playbackIdResponse().get().data().id() + ".m3u8"); 
}

2.7 Delete Live Stream Playback ID

This endpoint allows you to remove a specific playback ID associated with a live stream. Deleting a playback ID will revoke access to the live stream content linked to that ID, providing you with control over who can access your live streaming content.

Use the deletePlaybackIdOfStream() method to remove a playback ID for a live stream.

For more details refer to Delete Live Stream Playback ID API documentation.

String streamId = "your-stream-id"; 
String playbackId = "your-playback-id"; 
 
fastPix.playback().deletePlaybackIdOfStream(streamId, playbackId); 
 
System.out.println("Live stream playback ID deleted successfully!");

2.8 Get Live Stream Playback ID

Retrieves details about a previously created playback ID. If you provide the distinct playback ID that was given back to you in the previous stream or playbackId create request, FastPix will provide the relevant playback details such as the access policy.

Use the getLiveStreamPlaybackId() method to retrieve the playback policy for a specific live stream playback ID.

For more details refer to Get Live Stream Playback ID API documentation.

String streamId = "your-stream-id"; 
String playbackId = "your-playback-id"; 
 
GetLiveStreamPlaybackIdResponse response = fastPix.playback().getLiveStreamPlaybackId(streamId, playbackId); 
 
if (response.playbackIdResponse().isPresent()) { 
    System.out.println("Playback Policy: " + response.playbackIdResponse().get().data().accessPolicy()); 
}

2.9 Create Simulcast

Lets you to create a simulcast for a parent live stream. A simulcast enables you to broadcast the live stream to multiple platforms simultaneously (e.g., YouTube, Facebook, or Twitch). This feature is useful for expanding your audience reach across different platforms. However, a simulcast can only be created when the parent live stream is in an idle state (i.e., not currently live or disabled). Additionally, only one simulcast target can be created per API call.

Use the createSimulcastOfStream() method to create a new simulcast for a live stream.

For more details refer to Create Simulcast API documentation.

String streamId = "your-stream-id"; 
SimulcastRequest request = SimulcastRequest.builder() 
    .platform(SimulcastRequestPlatform.YOUTUBE) 
    .credentials(SimulcastRequestCredentials.builder() 
        .streamKey("your-youtube-stream-key") 
        .build()) 
    .build(); 
 
CreateSimulcastOfStreamResponse response = fastPix.simulcastStream().createSimulcastOfStream(streamId, request); 
 
if (response.simulcastResponse().isPresent()) { 
    System.out.println("Simulcast created successfully!"); 
    System.out.println("Simulcast ID: " + response.simulcastResponse().get().data().id()); 
}

2.10 Get Simulcast Details

Retrieves the details of a specific simulcast associated with a parent live stream. By providing both the streamId of the parent stream and the simulcastId, FastPix returns detailed information about the simulcast, such as the stream URL, the status of the simulcast (active or idle), and metadata.

Use the getSpecificSimulcastOfStream() method to retrieve details of a specific simulcast for a live stream.

For more details refer to Get Simulcast Details API documentation.

String streamId = "your-stream-id"; 
String simulcastId = "your-simulcast-id"; 
 
GetSpecificSimulcastOfStreamResponse response = fastPix.simulcastStream().getSpecificSimulcastOfStream(streamId, simulcastId); 
 
if (response.simulcastResponse().isPresent()) { 
    SimulcastResponseData simulcast = response.simulcastResponse().get().data(); 
    System.out.println("Simulcast ID: " + simulcast.id()); 
    System.out.println("Platform: " + simulcast.platform()); 
    System.out.println("Status: " + simulcast.status()); 
}

2.11 Update Simulcast

Allows you to enable or disable a specific simulcast associated with a parent live stream. The status of the simulcast can be updated at any point, whether the live stream is active or idle. However, once the live stream is disabled, the simulcast can no longer be modified.

Use the updateSpecificSimulcastOfStream() method to modify the configuration of a simulcast stream.

For more details refer to Update Simulcast API documentation.

String streamId = "your-stream-id"; 
String simulcastId = "your-simulcast-id"; 
SimulcastUpdateRequest request = SimulcastUpdateRequest.builder() 
    .status(SimulcastUpdateRequestStatus.IDLE) 
    .build(); 
 
UpdateSpecificSimulcastOfStreamResponse response = fastPix.simulcastStream().updateSpecificSimulcastOfStream(streamId, simulcastId, request); 
 
if (response.simulcastResponse().isPresent()) { 
    System.out.println("Simulcast updated successfully!"); 
}

2.12 Delete Simulcast

Allows you to delete a simulcast using its unique simulcastId, which was returned during the simulcast creation process. Deleting a simulcast stops the broadcast to the associated platform, but the parent stream will continue to run if it is live. This action is irreversible, and a new simulcast would need to be created if you want to resume streaming to the same platform.

Use the deleteSimulcastOfStream() method to remove a specific simulcast from a live stream.

For more details refer to Delete Simulcast API documentation.

String streamId = "your-stream-id"; 
String simulcastId = "your-simulcast-id"; 
 
fastPix.simulcastStream().deleteSimulcastOfStream(streamId, simulcastId); 
 
System.out.println("Simulcast deleted successfully!");

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 throw a models.errors.APIException exception, which has the following properties:

Property	Type	Description
`getMessage()`	String	The error message
`getStatusCode()`	int	The HTTP status code
`getRawResponse()`	HttpResponse	The raw HTTP response
`getBody()`	String	The response content

Example Error Handling

try { 
    CreateNewStreamResponse response = fastPix.startLiveStream().createNewStream() 
        .request(Optional.of(request)) 
        .call(); 
     
    if (response.liveStreamResponseDTO().isPresent()) { 
        // Handle success 
        System.out.println("Stream created: " + response.liveStreamResponseDTO().get().data().streamId()); 
    } 
} catch (UnauthorizedException ex) { 
    // Handle authentication errors 
    System.out.println("Authentication failed: " + ex.getMessage()); 
} catch (ValidationErrorResponse ex) { 
    // Handle validation errors 
    System.out.println("Validation error: " + ex.getMessage()); 
} catch (APIException ex) { 
    // Handle general API errors 
    System.out.println("API error: " + ex.getMessage()); 
}

Support & resources

Documentation: Visit the FastPix API Reference for detailed API documentation
GitHub Issues: Report bugs or request features on the GitHub repository
FastPix Platform: dashboard.fastpix.io
Contact us: Technical support

SDK Maturity

This SDK is currently in beta. While it’s production-ready, there may be breaking changes between versions without a major version update. We recommend:

Pinning to specific versions for production applications

Testing thoroughly before deploying updates

Monitoring the changelog for any breaking changes