Pumukit Hard Video Editor Bundle Laravel Package

Getting Started

This is a niche Symfony bundle that plugs a hard-cut video editor (re-encode / trim, not playlist-based soft cuts) into a Pumukit installation. It is not a standalone library — it only makes sense inside a working Pumukit deployment, so treat it as an extension of that platform rather than something you require into a generic Laravel/Symfony app.

Minimal steps:

1. Confirm your Pumukit version. Open the bundle's composer.json on GitHub and look at the require block (it will pin teltek/pumukit-* or pumukit/pumukit-* versions plus a Symfony range). Install only against a Pumukit install that matches, otherwise you will fight autoloading and template inheritance errors before you ever see the editor.
2. Install and register the bundle.
   • composer require teltek/pumukit-hard-video-editor-bundle
   • Register it in app/AppKernel.php (Symfony ≤3.x, which most Pumukit releases use) inside the bundles array, after the core Pumukit bundles it depends on.
   • Import its routing: Pumukit typically relies on app/config/routing.yml or the Pumukit route loader; add the bundle's routing resource if it isn't auto-collected.
   • Clear cache (bin/console cache:clear --env=prod) and rebuild assets (bin/console pumukit:assets:create or assetic:dump, depending on version).
3. Prerequisites on the host: ffmpeg/ffprobe on $PATH, a running Pumukit encoder worker (the bundle delegates the actual cut to the encoder, it does not shell out itself), and writable web/uploads / storage directories.
4. Where to look first: the bundle is small — read Controller/, Resources/views/, and Resources/config/ in that order. The controller shows the request/response flow and which services it injects; the templates show how the trimming UI is mounted into the multimedia object detail page; the config shows tunables.
5. First use case: create or open a MultimediaObject that has a master/original track, open the hard editor from the object's admin menu, select an in/out range, choose an output profile, and submit. You should get a new track (or new multimedia object, depending on implementation) whose duration matches the selection and which plays back correctly in the player.

Implementation Patterns

Treat the editor as a job producer. The real pattern in Pumukit is UI → Job → Encoder worker. The hard editor UI collects in/out points and a target profile, the bundle builds an encoder job referencing the source track, and PumukitEncoderBundle's worker performs the ffmpeg call. When debugging, always follow the job record before touching the UI.

Common integration patterns:

• Re-cut an existing recording. Take a lecture capture, trim the dead time at the start/end, and emit a new master track. This is the canonical use case and the easiest thing to demo.
• Extract a clip from a long master. Produce a short standalone object (e.g., a highlight) by selecting a sub-range and letting the bundle create a derived MultimediaObject or track — check which your version does, because it changes how you link or publish the result.
• Chain with encoder profiles. Point the editor at a profile that already exists in PumukitEncoderBundle (H.264/AAC MP4, HLS, etc.) so the hard cut inherits your house transcode settings rather than hardcoding ffmpeg flags.
• Menu / template extension. If you need the editor to appear under different roles or only for certain series, override the bundle's Twig templates from your app bundle (Pumukit uses standard Symfony bundle template inheritance, so an app/Resources/PumukitHardVideoEditorBundle/views/... override wins).
• Event hooks. If you need post-processing (transcript regeneration, thumbnail refresh, webhook to a VMS), hook the standard Pumukit multimedia-object/track events rather than editing inside the bundle — the bundle's controller should stay untouched so upgrades remain possible.
• Permission gating. Restrict who can perform hard cuts via Pumukit's role/permission system (ROLE_ADMIN, series-scoped roles). Hard cuts are destructive-ish (new files, storage growth), so gate them more tightly than soft edits.

Workflow tip: develop against a small local Pumukit with a short test video and a trivial encoder profile. The full loop (UI → job → worker → ffmpeg → new track) can take minutes per run; shrinking inputs to seconds makes iteration tolerable.

Gotchas and Tips

• Hard cuts need re-encoding at the edges. Cuts that are not on keyframes force ffmpeg to re-encode the surrounding GOPs; do not expect frame-accurate, instant, stream-copy output. Budget CPU and expect duration drift of a frame if you use -c copy.
• Master tracks only. The editor is designed around the original/master track. Attempting to cut a preview or a derived track usually fails at the encoder stage with a missing-file or unsupported-codec error.
• The encoder worker must actually be running. The most common "the editor did nothing" report is a submitted job sitting in waiting because pumukit:encoder:worker (or your supervisor unit for it) is not up. Check the job status before blaming the bundle.
• Version coupling is the biggest risk. With a single-star, low-traffic package, expect the bundle to be pinned to a specific Pumukit release. Diff composer.json against your install; if it disagrees, either upgrade Pumukit or fork the bundle — don't paper over it with --ignore-platform-reqs.
• Timecode precision and FPS. In/out points entered as HH:MM:SS are interpreted at the source track's frame rate; mixed-fps sources, VFR phone footage, and audio-lead offsets are the usual culprits for "the clip starts half a second early."
• Storage and object bloat. Each hard edit produces real files and usually a new track (sometimes a new multimedia object). For long-running deployments, add cleanup policy and monitor disk; there's no automatic dedup.
• Config quirks in Resources/config. Look for the bundle extension alias (likely pumukit_hard_video_editor) and any parameters.yml overrides — values like default profile, temp directory, and enabled object types are commonly set there. Pumukit bundles often merge config from app/config/config.yml under that alias.
• Debugging path: Symfony logs (var/logs/ or app/logs/) for controller exceptions; the encoder job payload and ffmpeg stderr in the encoder's log/temp directory for media failures; browser network tab for the UI's in/out payload if nothing reaches the job queue.
• Caches and assets are sticky. After template overrides or config changes, cache:clear alone is often not enough — also clear the Pumukit-specific caches and rebuild assets, otherwise you keep seeing old Twig or stale JS.
• Extension points to prefer over patching: Twig template overrides, Symfony event listeners, and custom encoder profiles. Avoid editing the bundle's controller directly, since with such a small upstream, a fork is more honest than a patch if you truly need behavior changes.
• No meaningful test suite is implied. Validate any upgrade with a manual smoke test: install, cut a 10-second range from a 1-minute master, confirm duration/playback/download and that the original track is untouched.