pushinbr / pam-native-video
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
Requires
- php: ^8.5
- pushinbr/pam-native: ^0.8 || ^0.9 || ^0.10 || ^1.0
Requires (Dev)
- phpstan/phpstan: ^2.1
- pushinbr/pam-native-plugin-kit: ^0.2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
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.
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-hlsand-ui1.9.3. Whenpam-native-media,pam-native-audioorpam-native-media-editor(Media31.10.1) are installed too, Gradle resolves every Media3 artifact to the newest requested version. - iOS: frameworks
AVFoundationandAVKit; 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
- API reference
- Example app
- PAM Native overview
- Plugin and native capability model
- PAM documentation
- Changelog
- Report an issue
Part of the PAM ecosystem
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