Search by

pushinbr / pam-native-video

DavidWilliamBalbino

Adaptive streaming, subtitles and native Media3/AVPlayer playback for PAM Native.

Package info

github.com/push-in/pam-native-video

Language:Swift

Type:pam-native-plugin

pkg:composer/pushinbr/pam-native-video

Statistics

Installs: 304

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.4.1 2026-11-11 23:52 UTC

This package is auto-updated.

Last update: 2026-11-11 23:55:34 UTC


README

pam-native-video: Adaptive HLS/DASH streaming, subtitles and DRM with native Media3 and AVPlayer playback.

Adaptive streaming and native playback for serious media apps.
Play HLS on iOS, HLS/DASH on Android, subtitles, tracks and DRM-protected sources while decode and rendering stay native.

Packagist Latest release PHP 8.5 CI License

Install · Quick example · Platforms · DRM · API · Issues

Install

Inside a PAM Native project, add only this capability:

pam composer require pushinbr/pam-native-video
pam doctor --fix

New to PAM? Create a project with pam init my-app --template native (see the PAM Native overview), then come back here. See what installation does.

Quick example

use Pam\Native\Video\VideoEventKind;
use Pam\Native\Video\VideoPlayer;
use Pam\Native\Video\VideoResizeMode;

return VideoPlayer::make('https://cdn.example.com/master.m3u8')
    ->autoPlay()
    ->controls()
    ->resizeMode(VideoResizeMode::Cover)
    ->onEvent(function (VideoEventKind $kind, array $event): void {
        // Progress: $event['positionMillis'], ['durationMillis'], ['bufferedMillis'].
    });

Decoder, buffering, controls and progress timing remain native rather than crossing the PHP bridge per frame. This package is a horizontal playback primitive: it does not install a feed, social network or streaming application template. A runnable app lives in example/.

Platform support

Platform Support Notes
Android API 26+ Media3 1.9.3 (ExoPlayer, DASH, HLS, UI); HLS, DASH, Widevine, ClearKey
iOS 15.0+ AVFoundation, AVKit; HLS, FairPlay
PAM Native 0.8.0 to < 2.0.0 From pam-native.plugin.json; PHP 8.5+

What installation does

pam composer require pushinbr/pam-native-video installs the package through the project's normal composer.json and composer.lock. Run pam doctor --fix afterward to validate the environment and regenerate native integration when required. The package is a PAM Native plugin with one native view (video.player); nothing is added to pam-native.json.

Use pam packages to inspect direct installed Composer dependencies and pam composer remove pushinbr/pam-native-video to uninstall the capability.

  • Android: no permissions besides network access. Dependencies: androidx.media3:media3-exoplayer, -exoplayer-dash, -exoplayer-hls and -ui 1.9.3. When pam-native-media, pam-native-audio or pam-native-media-editor (Media3 1.10.1) are installed too, Gradle resolves every Media3 artifact to the newest requested version.
  • iOS: frameworks AVFoundation and AVKit; no Info.plist keys. FairPlay needs a certificate and license server of your own.

What you can build

  • Streaming and IPTV applications
  • Social and editorial video
  • Offline-aware playback with native controls and subtitles
Native path Android Media3 · AVPlayer
Application model Composer package + generated native integration
Design rule Independent module; no feed, vertical or application template bundled

Protected playback

Protected playback supports Widevine and ClearKey on Android and FairPlay on iOS. An incompatible DRM scheme produces a native playback error instead of silently playing without DRM. License exchange runs inside the native player; credentials should be short-lived.

use Pam\Native\Video\VideoDrmConfiguration;
use Pam\Native\Video\VideoDrmScheme;
use Pam\Native\Video\VideoPlayer;

return VideoPlayer::make('https://cdn.example.com/movie/master.m3u8')
    ->drm(new VideoDrmConfiguration(
        scheme: VideoDrmScheme::FairPlay,
        licenseUrl: 'https://license.example.com/fps',
        authorization: 'Bearer '.$shortLivedToken,
        contentId: 'movie-42',
        certificateUrl: 'https://license.example.com/fairplay.cer',
    ))
    ->subtitle('https://cdn.example.com/subtitles/pt-BR.vtt')
    ->preferredForwardBuffer(15_000)
    ->autoPlay();

Features

Adaptive HLS playback, embedded subtitle/audio tracks, native controls, autoplay, looping, mute/volume, deterministic seek commands, configurable progress events and sandboxed local files. Android also supports DASH. External WebVTT, SRT and TTML subtitles are supported on both platforms; iOS loads at most 2 MiB and displays them in the AVKit content overlay. Embedded subtitles retain the platform's native track selection.

Every VideoPlayer method, event payload, DRM rule and error: docs/api-reference.md.

On macOS, run the focused subtitle, time and sandbox checks with swiftc ios/Sources/ExternalSubtitles.swift ios/Sources/VideoSafety.swift tests/ios-subtitles/main.swift -o /tmp/pam-video-ios-check && /tmp/pam-video-ios-check.

When to use it

The PAM Native core already ships <MediaPlayer> (Pam\Native\UI\MediaPlayer) for feed, story and chat media; Zé Chat plays its gallery, story and editor videos with it. Add this package when you need what the core player does not do: DRM (Widevine, ClearKey, FairPlay), DASH on Android, external WebVTT/SRT/TTML subtitles, bitrate caps, forward-buffer tuning and native transport controls.

Production checklist

  • Prefer adaptive HLS for both platforms; use DASH only for Android.
  • Keep progress intervals coarse enough for the product experience.
  • Pause or release playback when the owning screen loses visibility.
  • Run pam doctor, pam test, and a signed release build on every supported platform.
  • Exercise denial, cancellation, backgrounding, process restart and offline behavior before release.

Troubleshooting

  • Remote playback fails: verify HTTPS, codec, manifest and segment accessibility.
  • Seek appears ignored: issue it as an intentional state revision, not every render.
  • Subtitles are absent: inspect the embedded track, or check the external subtitle URL, format and 2 MiB iOS size limit.
  • Native integration is stale: run pam doctor --fix, rebuild the native host, and inspect the first reported diagnostic.

Compatibility

pushinbr/pam-native-video pushinbr/pam-native Android iOS
0.4.x >=0.8.0 <2.0.0 (tested with 1.14.x) API 26+, Media3 1.9.3 15+, external subtitles
0.3.x >=0.8.0 <1.0.0 API 26+ 15+, no external subtitles

Platform SDKs, credentials, entitlements, physical hardware and store configuration remain application responsibilities. Report security vulnerabilities through the repository security policy or GitHub private vulnerability reporting, not a public issue.

Docs

Part of the PAM ecosystem

PAM

PAM runs PHP natively on servers, desktops and phones. This repository is one piece of it.

PAM PAM Desktop PAM Native Ecosystem
the runtime and CLI native desktop apps in PHP native Android and iOS apps in PHP every official package and plugin

Docs: push-in.github.io/pam-docs · Issues

Apache License 2.0 · Made in Brazil by Pushin