pushinbr / pam-native-media
Native media inspection, image processing, video transcoding, thumbnails and embedded camera capture for PAM Native.
Package info
github.com/push-in/pam-native-media
Language:Kotlin
Type:pam-native-plugin
pkg:composer/pushinbr/pam-native-media
Requires
- php: ^8.5
- pushinbr/pam-native: ^1.53.1
Requires (Dev)
- pushinbr/pam-native-testing: ^0.2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v0.7.4
- v0.7.3
- v0.7.2
- v0.7.1
- v0.7.0
- v0.6.2
- v0.6.1
- v0.6.0
- v0.5.3
- v0.5.2
- v0.5.1
- v0.5.0
- v0.4.0
- v0.3.2
- v0.3.1
- v0.3.0
- v0.2.5
- v0.2.4
- v0.2.3
- v0.2.2
- v0.2.1
- v0.2.0
- v0.1.0
- dev-feat/camera-flash-capabilities
- dev-feat/port4-core-slim-20261028
- dev-fix/port4-camera-enabled-20261027
- dev-fix/ios-camera-enabled
- dev-fix/ios-swift-max
- dev-feat/media-camera-a11y
- dev-fix/camera-enable-bind
- dev-feat/pam-native-1.0
This package is auto-updated.
Last update: 2026-11-18 04:03:09 UTC
README
Inspect and prepare media without loading whole files into PHP.
Metadata, an EXIF-aware image pipeline, upload-ready video transcoding, batched thumbnails and an embedded camera, through native codecs with sandboxed paths and bounded results.
Install · Quick example · Platforms · Permissions · Docs · Issues
Install
Inside a PAM Native project, add only this capability:
pam composer require pushinbr/pam-native-media pam doctor --fix
Composer resolves the package and updates the normal composer.json and composer.lock; pam doctor --fix refreshes the generated native integration. The package is a PAM Native plugin (module media, view media.camera); nothing is added to pam-native.json. Use pam packages to inspect availability. New to PAM? Follow the five-minute PAM Native setup once (pam init my-app --template native).
Quick example
use Pam\Native\Media\{ImageFormat, ImageResult, Media, ResizeMode, TranscodeResult, VideoPreset}; // Upload-ready MP4 (H.264 Main / AAC-LC, bounded size, 2 s keyframes, fast start) $task = Media::transcode('captures/clip.mov') ->to('outbox/clip.mp4') ->preset(VideoPreset::Chat720p) ->fastStart() ->progress(fn (float $p) => $this->encoding = $p) ->run( fn (TranscodeResult $video) => $this->send($video->path), fn (string $error) => $this->fail($error), ); // $task->cancel(); // Image pipeline: EXIF orientation first, then operations in call order Media::image('captures/photo.jpg') ->resize(1920, 1920, ResizeMode::Contain) ->onlyScaleDown() ->format(ImageFormat::Webp, 82) ->save('outbox/photo.webp', fn (ImageResult $image) => $this->send($image->path));
Paths are relative to the PAM file sandbox; PHP never holds pixel data and outputs are written atomically. Full walk-through (presets, thumbnails, the 0.3 API, platform notes): docs/usage.md. Embedded camera: docs/camera.md. A production example: docs/zechat-example.md. A runnable one-screen app: example/.
Platform support
| Platform | Support | Notes |
|---|---|---|
| Android | API 24+ | Media3 Transformer 1.10.1, CameraX 1.6.1, ExifInterface 1.4.2 |
| iOS | 15.0+ | AVFoundation, ImageIO, Photos; transcode and image pipeline since 0.5, not yet validated on a device |
| PAM Native | 1.46.0 to < 2.0.0 | From pam-native.plugin.json; PHP 8.5+ |
Permissions and requirements
| Platform | Declared by the plugin |
|---|---|
| Android | CAMERA, RECORD_AUDIO, READ_MEDIA_IMAGES, READ_MEDIA_VIDEO, READ_MEDIA_VISUAL_USER_SELECTED, READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE (all android.permission.*) |
| iOS | NSCameraUsageDescription ("Capture photos and videos."), NSMicrophoneUsageDescription ("Record audio with videos.") |
Only CameraView uses the camera and microphone: request PermissionKind::Camera/Microphone before enabling the view. Other plugins that declare the same iOS keys (pam-native-webrtc, pam-native-camera) use the same strings, because the CLI rejects conflicting values.
Android dependencies: CameraX 1.6.1 (camera-camera2, camera-lifecycle, camera-view, camera-video), Media3 1.10.1 (media3-common, media3-effect, media3-transformer) and ExifInterface 1.4.2. iOS frameworks: AVFoundation, CoreGraphics, CoreMedia, CoreVideo, ImageIO, UniformTypeIdentifiers, Photos, UIKit.
What you can build
- Gallery and attachment pickers
- Upload preparation and validation
- Fast thumbnail pipelines for local media libraries
| Best for | A focused capability you can add to any PAM Native application |
| Native path | MediaMetadataRetriever · Media3 · CameraX · AVFoundation |
| Application model | Composer package + generated native integration |
| Design rule | Independent module; no feed, vertical or application template bundled |
Capabilities
Media::transcode(): H.264/AAC MP4 with presetsCompact480p,Chat720p,Chat1080p,Adaptive, bitrate cap, fast start, progress and cancellationMedia::image(): EXIF-oriented resize, crop, rotate, flip and JPEG/PNG/WebP encoding, plusprobe()Media::thumbnails(): 1 to 100 thumbnails in one native call (sandbox paths or HTTPS video URLs)(new Media())->probe()/thumbnail(): the unchanged 0.3 APICameraView: lifecycle-aware embedded camera with revision-based photo/video capture, flash and torch, recording zoom ramps, pinch zoom, double-tap lens flip and Android tap to focusMediaLibrary(gallery assets, albums, thumbnails, save) andViewCapture(capture a mounted view to an image)- Stable cross-plugin entry points (
dev.pam.media.MediaTranscodingon the JVM,PamMediaTranscodingon iOS) used bypushinbr/pam-native-background-transfer
Full API: docs/api-reference.md.
Production checklist
- Request camera and microphone permissions before enabling capture.
- Move or upload captures using their sandbox-relative
FileReference. - Bound recording duration, thumbnail dimensions and retained media.
- Run
pam doctor,pam testand a signed release build on every supported platform. - Exercise denial, cancellation, backgrounding, process restart and offline behavior before release.
Troubleshooting
- A path is rejected: use app-relative paths and never absolute/traversal paths.
- Preview works but capture fails: verify permissions and available device storage.
- Combined streams fail on a device: enable only the outputs required by the selected mode.
- Native integration is stale: run
pam doctor --fix, rebuild the native host and inspect the first reported diagnostic.
Compatibility
pushinbr/pam-native-media |
pushinbr/pam-native |
Android | iOS |
|---|---|---|---|
| 0.7.x (current manifest) | >=1.46.0 <2.0.0 |
API 26+ | 15+ |
| 0.5.x | >=1.0.35 <2.0.0 (tested with 1.14.x) |
API 26+ | 15+ (transcode, image pipeline, batches) |
| 0.4.x | >=1.0.35 <2.0.0 |
API 26+ | Probe, thumbnails and camera only |
Core extraction (1.46): requires pushinbr/pam-native ^1.46. The core keeps deprecated PHP aliases through 1.46; they are removed in 1.47. Native wire contracts are retained. Swift compilation and device QA remain pending.
Platform SDKs, credentials, entitlements, physical hardware and store configuration remain application responsibilities.
Tests
pam composer test runs the PHP contract suite. Android JVM tests (android/src/test: resize geometry, fast-start rewriting, options, recording and gesture zoom math) and instrumented tests (android/src/androidTest: EXIF pipeline, thumbnails, Media3 transcode, cross-plugin entry point) run from a PAM Android host that includes this plugin with testDebugUnitTest / connectedDebugAndroidTest. JVM tests require JUnit 4 and the JVM org.json implementation on the test classpath (the Android SDK JSON stub cannot execute parser tests).
On macOS, run the focused sizing and sandbox checks with swiftc ios/Sources/MediaThumbnailSizing.swift ios/Sources/MediaSandboxPath.swift tests/ios-thumbnail/main.swift -o /tmp/pam-media-ios-check && /tmp/pam-media-ios-check.
Docs
- Usage: transcoding, images and thumbnails
- Embedded camera
- API reference
- A real example: Zé Chat
- Runnable demo app
- PAM Native overview
- Plugin and native capability model
- Changelog
- Report an issue: security vulnerabilities go through the repository security policy or GitHub private vulnerability reporting, not a public 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