README

This package provides shared PHP interfaces, DTOs, enums and collections that define a common contract for video generation providers.

It is designed to be used by both video generation clients and concrete provider implementations so they can communicate using a stable, provider-agnostic API.

Requirements

PHP 8.3 or higher
adachsoft/collection ^3.0

Installation

Install via Composer:

composer require adachsoft/video-generation-contracts

Provided building blocks

Contracts

AdachSoft\VideoGenerationContracts\Contract\VideoGeneratorInterface
Main entry point for video generation providers (submitting requests, fetching jobs, listing jobs, discovering capabilities).
AdachSoft\VideoGenerationContracts\Contract\VideoWebhookHandlerInterface
Contract for handling asynchronous webhook callbacks with job status updates.

DTOs

VideoRequestDto – describes a video generation request (format, aspect ratio, quality, duration, prompt, input media).
VideoResultDto – describes the final generated video (download URL, size, duration, metadata).
VideoJobDto – represents a long-running generation job with status and timestamps.
VideoMetadataDto – additional metadata about the result.
InputMediaDto – represents a single media input (image or video) with an optional role.
ProviderParametersDto – optional provider-specific configuration.
VideoGeneratorCapabilitiesDto – describes what a concrete provider supports.

Enums

VideoFormatEnum – output format (e.g. MP4, WebM, GIF).
VideoAspectRatioEnum – aspect ratio (landscape, portrait, square, etc.).
VideoQualityEnum – quality presets (draft, standard, high).
VideoStatusEnum – job status (pending, processing, done, failed, cancelled).
InputMediaTypeEnum – input media type (image, video).
InputMediaRoleEnum – logical role of a media input (content, style, reference).

Collections

Immutable and mutable collections built on top of adachsoft/collection for:

VideoJobCollection
VideoFormatCollection
VideoAspectRatioCollection
VideoQualityCollection
InputMediaCollection
InputMediaTypeCollection
InputMediaRoleCollection

These collections provide type-safe storage and convenience helpers such as filtering by status, role or type.

Exceptions

Domain-specific exceptions that providers and clients can share:

InvalidPromptException
UnsupportedFormatException
UnsupportedInputModeException
RateLimitException
GenerationFailedException
VideoGenerationException (base class)

Basic usage

Implementing a provider

To integrate a concrete video generation provider, implement VideoGeneratorInterface in your library or application:

<?php

declare(strict_types=1);

use AdachSoft\VideoGenerationContracts\Contract\VideoGeneratorInterface;
use AdachSoft\VideoGenerationContracts\Dto\VideoJobDto;
use AdachSoft\VideoGenerationContracts\Dto\VideoRequestDto;
use AdachSoft\VideoGenerationContracts\Enum\VideoStatusEnum;
use AdachSoft\VideoGenerationContracts\Collection\VideoJobCollection;

final class AcmeVideoGenerator implements VideoGeneratorInterface
{
    public function generate(VideoRequestDto $videoRequestDto): VideoJobDto
    {
        // submit request to provider API and return initial job
    }

    public function getJob(string $id): VideoJobDto
    {
        // fetch job status from provider
    }

    public function listJobs(?VideoStatusEnum $videoStatusEnum = null): VideoJobCollection
    {
        // list jobs, optionally filtered by status
    }

    public function getProviderName(): string
    {
        return 'acme-video';
    }
}

Consuming a provider

Client code can depend purely on the contracts without coupling to a specific implementation:

<?php

declare(strict_types=1);

use AdachSoft\VideoGenerationContracts\Contract\VideoGeneratorInterface;
use AdachSoft\VideoGenerationContracts\Dto\InputMediaDto;
use AdachSoft\VideoGenerationContracts\Dto\InputMediaCollection;
use AdachSoft\VideoGenerationContracts\Dto\VideoRequestDto;
use AdachSoft\VideoGenerationContracts\Enum\InputMediaTypeEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoAspectRatioEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoFormatEnum;
use AdachSoft\VideoGenerationContracts\Enum\VideoQualityEnum;

final class GenerateIntroVideoHandler
{
    public function __construct(
        private readonly VideoGeneratorInterface $videoGenerator,
    ) {
    }

    public function __invoke(string $prompt, string $imageUrl): void
    {
        $media = new InputMediaCollection([
            new InputMediaDto($imageUrl, InputMediaTypeEnum::Image),
        ]);

        $request = new VideoRequestDto(
            VideoFormatEnum::Mp4,
            VideoAspectRatioEnum::Landscape,
            VideoQualityEnum::Standard,
            15,
            $prompt,
            $media,
        );

        $job = $this->videoGenerator->generate($request);

        // persist job id, trigger polling or wait for webhooks
    }
}

Versioning and license

This library is versioned via Git tags only.
License: MIT.

adachsoft / video-generation-contracts

Maintainers

Package info

Statistics

Security