Build a PHP‑Powered AI Video Assistant with Webman, Neuron AI & FFmpeg

Introduction

As a PHP developer you can build an intelligent video‑processing assistant that understands natural‑language commands and performs common video editing tasks such as transcoding, concatenation, screenshot, audio extraction, watermarking and metadata queries.

Technology Stack

PHP 8.2+ – programming language.

Webman – high‑performance PHP framework based on Workerman, suitable for long‑running connections, asynchronous tasks and API services.

Neuron AI – PHP‑specific agent framework (https://github.com/neuron-core/neuron-ai) that supports tool calling, middleware, memory management and multimodal input/output; works with various LLM providers (OpenAI, Qwen, DeepSeek, Tencent Yuanbao, etc.).

FFmpeg – command‑line tool for audio/video processing.

Core Implementation Idea

Define each FFmpeg operation as a Tool class that implements the Neuron AI Tool interface, specifying its purpose and parameters.

Create an FFmpegAgent class that extends NeuronAI\Agent\Agent, registers all tools, and provides a system prompt describing the agent’s role.

Expose a Webman controller that receives a natural‑language request, forwards it to the agent, and returns the processed result or file path.

Step 1 – Create the FFmpegAgent

<?php
/** 
 * @desc FFmpeg AI Agent - process audio/video files via natural language
 * @author Tinywan (ShaoBo Wan)
 *
 * Features:
 * - Video transcoding (multiple resolutions)
 * - Video concatenation
 * - Video screenshot
 * - Audio extraction
 * - Watermark (image/text)
 * - Video information query
 */
declare(strict_types=1);

namespace app
euron;

use NeuronAI\Agent\Agent;
use NeuronAI\Agent\SystemPrompt;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\ZAI\ZAI;
use app
euron\tool\VideoTranscodeTool;
use app
euron\tool\VideoConcatTool;
use app
euron\tool\VideoScreenshotTool;
use app
euron\tool\AudioExtractTool;
use app
euron\tool\VideoWatermarkTool;
use app
euron\tool\VideoInfoTool;

class FFmpegAgent extends Agent
{
    protected function provider(): AIProviderInterface
    {
        return new ZAI(
            key: '7312460bbad94517a18981c93a12c2ea.xxxxxxxxxxxxx',
            model: 'glm-5.1',
            parameters: [],
        );
    }

    public function instructions(): string
    {
        return (string) new SystemPrompt(
            background: ['You are FFmpeg Agent, a professional audio‑video processing assistant.'],
            steps: ['Understand user intent', 'Invoke appropriate tool', 'Return final result'],
            toolsUsage: ['Use absolute paths', 'Output full file path', 'Provide clear errors', 'Only output final result, no reasoning'],
        );
    }

    protected function tools(): array
    {
        return [
            new VideoInfoTool(),
            new VideoScreenshotTool(),
            new VideoWatermarkTool(),
            new VideoTranscodeTool(),
            new VideoConcatTool(),
            new AudioExtractTool(),
        ];
    }
}
?>

Step 2 – Implement a Sample Tool (VideoInfoTool)

<?php
/** @desc Video information query tool */
declare(strict_types=1);

namespace app
euron\tool;

use NeuronAI\Tools\Tool;
use NeuronAI\Tools\ToolProperty;
use NeuronAI\Tools\PropertyType;

class VideoInfoTool extends Tool
{
    public function __construct()
    {
        parent::__construct(
            'video_info',
            'Retrieve detailed information of a video/audio file, including resolution, duration, frame rate, codec, etc.'
        );
    }

    protected function properties(): array
    {
        return [
            new ToolProperty(
                name: 'input_file',
                type: PropertyType::STRING,
                description: 'Full path of the input video/audio file',
                required: true,
            ),
        ];
    }

    public function __invoke(string $input_file): string
    {
        if (!file_exists($input_file)) {
            return "Error: File not found - {$input_file}";
        }

        $cmd = sprintf('ffprobe -v quiet -print_format json -show_format -show_streams %s', escapeshellarg($input_file));
        $output = shell_exec($cmd);
        if (!$output) {
            return "Error: Unable to retrieve file information, ensure ffprobe is installed";
        }

        $info = json_decode($output, true);
        if (!$info) {
            return "Error: Failed to parse file information";
        }

        return $this->formatVideoInfo($input_file, $info);
    }

    // Helper methods formatFileSize, formatDuration, formatBitrate, formatFrameRate omitted for brevity
}
?>

Step 3 – Controller Integration

<?php
/** @desc FFmpeg Agent controller */
declare(strict_types=1);

namespace app\controller;

use NeuronAI\Chat\Messages\UserMessage;
use NeuronAI\Chat\Messages\ContentBlocks\TextContent;
use NeuronAI\Chat\Messages\ContentBlocks\ReasoningContent;
use support\Request;
use support\Response;

class FfmpegController
{
    public function index(): Response
    {
        return view('ffmpeg/index');
    }

    public function chat(Request $request): Response
    {
        $message = $request->post('message', '');
        if (empty($message)) {
            return json(['error' => 'Message cannot be empty'], 400);
        }

        $agent = \app
euron\FFmpegAgent::make();

        try {
            $response = $agent->chat(new UserMessage($message));
            $msg = $response->getMessage();

            $content = '';
            foreach ($msg->getContentBlocks() ?? [] as $block) {
                if ($block instanceof TextContent && !($block instanceof ReasoningContent)) {
                    $content .= $block->content;
                }
            }

            if (empty($content)) {
                $content = 'Processing completed, but no output was returned';
            }

            return json(['success' => true, 'message' => $content]);
        } catch (\Exception $e) {
            return json(['success' => false, 'error' => $e->getMessage()], 500);
        }
    }
}
?>

Demonstration

Running the agent in a browser shows the following results:

Video information extraction

Video screenshot

Video transcoding

These screenshots illustrate the agent’s ability to retrieve metadata, capture frames, and re‑encode video files based on natural‑language prompts.