Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

Keep LTX-2.3 image-to-video on the reference, and trim a clip's start

Claude0c7a249f1787
diff --git a/client/src/components/media/MediaCard.jsx b/client/src/components/media/MediaCard.jsx
index d870f1a88e..dcf256f3d6 100644
--- a/client/src/components/media/MediaCard.jsx
+++ b/client/src/components/media/MediaCard.jsx
@@ -205,6 +205,7 @@ function MediaCard({
{[
item.stitchedFrom && { label: 'stitched', cls: 'bg-port-success/80 text-white' },
item.upscaledFrom && { label: '2×', cls: 'bg-port-accent/80 text-white' },
+ item.trimmedFrom && { label: 'trimmed', cls: 'bg-port-border text-white', title: 'Starts at a later frame of another clip' },
item.extractedFromVideoId && { label: 'frame', cls: 'bg-port-warning/80 text-black', title: 'Extracted from video' },
].filter(Boolean).map((b) => (
<span key={b.label} title={b.title} className={`pointer-events-auto text-[9px] px-1 py-0.5 rounded ${b.cls}`}>{b.label}</span>
diff --git a/client/src/components/media/MediaLightbox.jsx b/client/src/components/media/MediaLightbox.jsx
index 107f6f48c4..cb83cca44b 100644
--- a/client/src/components/media/MediaLightbox.jsx
+++ b/client/src/components/media/MediaLightbox.jsx
@@ -4,6 +4,7 @@ import {
X, Copy, Sparkles, Film, Image as ImageIcon, Download, Eraser, Wand2,
ChevronLeft, ChevronRight, Maximize2, Minimize2, Star, Box, ScanEye, Aperture,
} from 'lucide-react';
+import VideoStartTrimControl from './VideoStartTrimControl';
import PromptRefineModal from './PromptRefineModal';
import { PromptFromMediaModal } from './PromptFromMedia';
import AddToCollectionMenu from './AddToCollectionMenu';
@@ -132,6 +133,7 @@ export default function MediaLightbox({
onPromptChange,
onPromptAnalysis,
onPosterChange,
+ onTrimStart,
variantGroup = null,
onSelectVariant,
onFilmLookComplete,
@@ -480,6 +482,8 @@ export default function MediaLightbox({
onPromptChange={item.compact ? undefined : onPromptChange}
onPosterChange={onPosterChange}
getPlayhead={() => videoRef.current?.currentTime ?? 0}
+ onTrimStart={onTrimStart}
+ videoRef={videoRef}
variantGroup={variantGroup}
onSelectVariant={onSelectVariant}
onFilmLook={!isVideo && item.filename ? () => setFilmLookOpen(true) : undefined}
@@ -525,7 +529,7 @@ function SettingsPane({
item, meta, isVideo,
onClose, onRemix, onSendToImage, onSendToVideo, onSendTo3d, onContinue, onClean, onRegenerate, onRemoveWatermark, regenAvailable, regenBounds,
copy, onRefine, onPromptFrom,
- annotation, onAnnotationChange, onPromptChange, onPosterChange, getPlayhead,
+ annotation, onAnnotationChange, onPromptChange, onPosterChange, getPlayhead, onTrimStart, videoRef,
variantGroup, onSelectVariant, onFilmLook,
}) {
const asideClasses = 'md:w-80 lg:w-96 shrink-0 flex flex-col border-t md:border-t-0 md:border-l border-port-border min-h-0 max-h-dvh-cap [--dvh-cap:40vh] [--dvh-cap-dynamic:40dvh] md:[--dvh-cap:92vh] md:[--dvh-cap-dynamic:92dvh] [--dvh-inset:2rem]';
@@ -1019,6 +1023,10 @@ function SettingsPane({
{posterError && <p role="alert" className="text-port-error">{posterError}</p>}
</div>
)}
+ {isVideo && onTrimStart && item.id && (
+ <VideoStartTrimControl videoRef={videoRef} fps={item.fps} sourceKey={item.key}
+ onTrim={(startSec) => onTrimStart(item, startSec)} />
+ )}
{isVideo && item.id && item.previewUrl && (
<a href={`/api/video-gen/history/${encodeURIComponent(item.id)}/sharing-download`} download
className="min-h-[44px] flex items-center px-2 rounded bg-port-border text-white">Download for sharing</a>
diff --git a/client/src/components/media/MediaPreview.jsx b/client/src/components/media/MediaPreview.jsx
index f7165f08b7..c412949a86 100644
--- a/client/src/components/media/MediaPreview.jsx
+++ b/client/src/components/media/MediaPreview.jsx
@@ -3,7 +3,7 @@ import MediaLightbox from './MediaLightbox';
import { getMediaNavProps } from '../../lib/mediaNavigation';
import { computeImageVariantGroup } from './variants';
import useImageVariants from '../../hooks/useImageVariants';
-import { updateImagePrompt, updateVideoPrompt, updateVideoPoster } from '../../services/apiImageVideo';
+import { trimVideoStart, updateImagePrompt, updateVideoPrompt, updateVideoPoster } from '../../services/apiImageVideo';
// Thin wrapper around MediaLightbox that owns the consistent wiring every
// page repeated by hand: open/close, prev/next nav, and the annotation
@@ -23,6 +23,7 @@ export default function MediaPreview({
updateAnnotation,
onPromptSaved,
onPosterSaved,
+ onTrimmed,
...handlers
}) {
const [promptOverride, setPromptOverride] = useState(null);
@@ -59,6 +60,13 @@ export default function MediaPreview({
onPosterSaved?.(item, result);
return result;
}, [onPosterSaved]);
+ // The trim writes a new gallery clip; only a host that can list it (and open
+ // it) offers the control.
+ const trimStart = useCallback(async (item, startSec) => {
+ const { video } = await trimVideoStart(item.id, startSec, { silent: true });
+ onTrimmed(video, item);
+ return video;
+ }, [onTrimmed]);
// Original-vs-cleaned toggle, computed over the UNION of the host's items
// and the image's fetched lineage — neither source alone is complete. The
// host list misses a copy it never held (see useImageVariants), while the
@@ -133,6 +141,7 @@ export default function MediaPreview({
onAnnotationChange={preview && updateAnnotation ? (patch) => updateAnnotation(preview.key, patch) : undefined}
onPromptChange={savePrompt}
onPosterChange={savePoster}
+ onTrimStart={onTrimmed ? trimStart : undefined}
variantGroup={variantGroup}
onSelectVariant={onSelectVariant}
onPromptAnalysis={handlePromptAnalysis}
diff --git a/client/src/components/media/MediaPreview.test.jsx b/client/src/components/media/MediaPreview.test.jsx
index 062619a9e5..59dd3b2272 100644
--- a/client/src/components/media/MediaPreview.test.jsx
+++ b/client/src/components/media/MediaPreview.test.jsx
@@ -4,12 +4,13 @@ import { fireEvent, render, screen, waitFor } from '@testing-library/react';
import { MemoryRouter, useLocation } from 'react-router';
import MediaPreview from './MediaPreview';
import usePreviewRoute from '../../hooks/usePreviewRoute';
-import { updateVideoPrompt, updateVideoPoster, listImageVariants, listMediaGalleryPage } from '../../services/apiImageVideo';
+import { trimVideoStart, updateVideoPrompt, updateVideoPoster, listImageVariants, listMediaGalleryPage } from '../../services/apiImageVideo';
vi.mock('../../services/apiImageVideo', () => ({
updateImagePrompt: vi.fn(),
updateVideoPrompt: vi.fn(),
updateVideoPoster: vi.fn(),
+ trimVideoStart: vi.fn(),
listImageVariants: vi.fn(),
listMediaGalleryPage: vi.fn(),
}));
@@ -18,8 +19,9 @@ vi.mock('../../services/apiImageVideo', () => ({
// its own interaction coverage; this stub exposes the item it receives and
// invokes the same callback the real Save prompt button uses.
vi.mock('./MediaLightbox', () => ({
- default: ({ item, onPromptChange, onPosterChange, variantGroup, onSelectVariant }) => item ? (
+ default: ({ item, onPromptChange, onPosterChange, onTrimStart, variantGroup, onSelectVariant }) => item ? (
<div data-testid="lightbox">
+ {onTrimStart && <button type="button" onClick={() => onTrimStart(item, 1.25)}>Start clip here</button>}
<span data-testid="lightbox-poster">{item.previewUrl}</span>
<button onClick={() => onPosterChange(item, 12.4)}>Save poster</button>
<span data-testid="lightbox-prompt">{item.prompt}</span>
@@ -289,3 +291,18 @@ it('applies a saved poster immediately and reports the updated history fields to
await waitFor(() => expect(screen.getByTestId('lightbox-poster')).toHaveTextContent('/data/video-thumbnails/new-poster.jpg'));
expect(saved).toHaveBeenCalledWith(VIDEO, { id: VIDEO.id, thumbnail: 'new-poster.jpg', posterSec: 12.4 });
});
+
+// Uniquely catches a trim that never reaches the host's gallery, or a control
+// offered by a host that has nowhere to show the new clip.
+it('hands the trimmed clip to the host, and offers no trim to a host that cannot list it', async () => {
+ const trimmed = { id: 'video-2', filename: 'video-2.mp4', trimmedFrom: VIDEO.id };
+ trimVideoStart.mockResolvedValue({ ok: true, video: trimmed });
+ const onTrimmed = vi.fn();
+ const { rerender } = render(<MediaPreview preview={VIDEO} setPreview={() => {}} items={[VIDEO]} onTrimmed={onTrimmed} />);
+ fireEvent.click(screen.getByRole('button', { name: 'Start clip here' }));
+ await waitFor(() => expect(onTrimmed).toHaveBeenCalledWith(trimmed, VIDEO));
+ expect(trimVideoStart).toHaveBeenCalledWith(VIDEO.id, 1.25, { silent: true });
+
+ rerender(<MediaPreview preview={VIDEO} setPreview={() => {}} items={[VIDEO]} />);
+ expect(screen.queryByRole('button', { name: 'Start clip here' })).toBeNull();
+});
diff --git a/client/src/components/media/VideoStartTrimControl.jsx b/client/src/components/media/VideoStartTrimControl.jsx
new file mode 100644
index 0000000000..fb2e711347
--- /dev/null
+++ b/client/src/components/media/VideoStartTrimControl.jsx
@@ -0,0 +1,80 @@
+import { useEffect, useState } from 'react';
+import { ChevronLeft, ChevronRight, Scissors } from 'lucide-react';
+
+// Frame stepping still needs a rate when a clip recorded none; the server
+// snaps the chosen time to the clip's real frame grid either way.
+const FALLBACK_FPS = 24;
+
+// The frame on screen at `sec`: frame n spans [n, n + 1) / fps.
+const frameAt = (sec, rate) => Math.floor((Number(sec) || 0) * rate + 1e-6);
+
+// Pick a later start frame on a playing clip and keep the clip from there.
+// Shared by every surface that shows a video take (Video Gen result, music
+// video clip takes): the host owns the <video> element and what a trim does,
+// so `onTrim(startSec)` returns a promise and this control only shows the
+// frame, steps it, and reports a failure inline. `sourceKey` names the clip
+// on screen, so a host that swaps the element re-subscribes.
+export default function VideoStartTrimControl({ videoRef, fps, onTrim, sourceKey, disabled = false }) {
+ const rate = Number(fps) > 0 ? Number(fps) : FALLBACK_FPS;
+ const [frame, setFrame] = useState(0);
+ const [saving, setSaving] = useState(false);
+ const [error, setError] = useState(null);
+
+ // The ref is filled at commit, so it is read here rather than during render.
+ useEffect(() => {
+ const video = videoRef?.current;
+ if (!video) return undefined;
+ const sync = () => setFrame(frameAt(video.currentTime, rate));
+ sync();
+ video.addEventListener('timeupdate', sync);
+ video.addEventListener('seeked', sync);
+ return () => {
+ video.removeEventListener('timeupdate', sync);
+ video.removeEventListener('seeked', sync);
+ };
+ }, [videoRef, rate, sourceKey]);
+
+ const step = (delta) => {
+ const el = videoRef?.current;
+ if (!el) return;
+ el.pause();
+ const current = frameAt(el.currentTime, rate);
+ const max = Number.isFinite(el.duration) ? Math.floor(el.duration * rate) : Infinity;
+ const next = Math.min(max, Math.max(0, current + delta));
+ // Aim at the middle of the frame so a rounding seek can't land on its neighbour.
+ el.currentTime = (next + 0.5) / rate;
+ setFrame(next);
+ };
+
+ const trim = async () => {
+ const el = videoRef?.current;
+ if (!el || saving) return;
+ el.pause();
+ setSaving(true);
+ setError(null);
+ // Send the frame's exact start so the server's snap lands on this frame.
+ await Promise.resolve(onTrim(frameAt(el.currentTime, rate) / rate))
+ .catch((err) => setError(err?.message || 'Trim failed'))
+ .finally(() => setSaving(false));
+ };
+
+ const busy = disabled || saving;
+ return (
+ <div className="w-full flex flex-wrap items-center gap-2">
+ <button type="button" aria-label="Previous frame" disabled={busy} onClick={() => step(-1)}
+ className="min-h-[44px] min-w-[44px] flex items-center justify-center rounded bg-port-border text-white disabled:opacity-50">
+ <ChevronLeft className="w-4 h-4" />
+ </button>
+ <span className="text-xs text-gray-300 tabular-nums min-w-[4.5rem] text-center">Frame {frame}</span>
+ <button type="button" aria-label="Next frame" disabled={busy} onClick={() => step(1)}
+ className="min-h-[44px] min-w-[44px] flex items-center justify-center rounded bg-port-border text-white disabled:opacity-50">
+ <ChevronRight className="w-4 h-4" />
+ </button>
+ <button type="button" disabled={busy || frame < 1} onClick={trim}
+ className="min-h-[44px] flex items-center gap-1.5 px-2 rounded bg-port-border text-white disabled:opacity-50">
+ <Scissors className="w-3.5 h-3.5" /> {saving ? 'Trimming…' : 'Start clip here'}
+ </button>
+ {error && <p role="alert" className="w-full text-xs text-port-error">{error}</p>}
+ </div>
+ );
+}
diff --git a/client/src/components/media/VideoStartTrimControl.test.jsx b/client/src/components/media/VideoStartTrimControl.test.jsx
new file mode 100644
index 0000000000..9a5bce3bc8
--- /dev/null
+++ b/client/src/components/media/VideoStartTrimControl.test.jsx
@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import VideoStartTrimControl from './VideoStartTrimControl.jsx';
+
+// A stand-in <video>: happy-dom has no decoder, so currentTime/duration are
+// plain fields the test drives.
+const fakeVideo = ({ currentTime = 0, duration = 4 } = {}) => {
+ const el = document.createElement('video');
+ Object.defineProperty(el, 'duration', { value: duration });
+ let time = currentTime;
+ Object.defineProperty(el, 'currentTime', { get: () => time, set: (t) => { time = t; } });
+ el.pause = vi.fn();
+ return el;
+};
+
+describe('VideoStartTrimControl', () => {
+ // Uniquely catches an off-by-one between the frame shown and the start the
+ // server is asked to keep (the server rounds startSec * fps to a frame).
+ it('steps frame by frame and trims from the exact start of the frame on screen', async () => {
+ const video = fakeVideo({ currentTime: 1.01 });
+ const onTrim = vi.fn(async () => {});
+ render(<VideoStartTrimControl videoRef={{ current: video }} fps={24} onTrim={onTrim} />);
+ expect(screen.getByText('Frame 24')).toBeInTheDocument();
+
+ fireEvent.click(screen.getByRole('button', { name: 'Next frame' }));
+ fireEvent.click(screen.getByRole('button', { name: 'Next frame' }));
+ fireEvent.click(screen.getByRole('button', { name: 'Previous frame' }));
+ expect(video.pause).toHaveBeenCalled();
+ expect(screen.getByText('Frame 25')).toBeInTheDocument();
+
+ await act(async () => { fireEvent.click(screen.getByRole('button', { name: /Start clip here/ })); });
+ expect(onTrim).toHaveBeenCalledWith(25 / 24);
+ });
+
+ it('shows a failed trim inline and stays usable', async () => {
+ const video = fakeVideo({ currentTime: 0.5 });
+ const onTrim = vi.fn(async () => { throw new Error('Pick a frame before the end of the clip'); });
+ render(<VideoStartTrimControl videoRef={{ current: video }} fps={24} onTrim={onTrim} />);
+ fireEvent.click(screen.getByRole('button', { name: /Start clip here/ }));
+ expect(await screen.findByRole('alert')).toHaveTextContent('Pick a frame before the end of the clip');
+ await waitFor(() => expect(screen.getByRole('button', { name: /Start clip here/ })).not.toBeDisabled());
+ });
+
+ it('cannot trim at the first frame', () => {
+ render(<VideoStartTrimControl videoRef={{ current: fakeVideo() }} fps={24} onTrim={vi.fn()} />);
+ expect(screen.getByRole('button', { name: /Start clip here/ })).toBeDisabled();
+ });
+});
diff --git a/client/src/components/media/normalize.js b/client/src/components/media/normalize.js
index 033c74e2cb..c564a04ade 100644
--- a/client/src/components/media/normalize.js
+++ b/client/src/components/media/normalize.js
@@ -145,6 +145,7 @@ export function normalizeVideo(v) {
mode: v.mode,
stitchedFrom: v.stitchedFrom,
upscaledFrom: v.upscaledFrom,
+ trimmedFrom: v.trimmedFrom,
loraNames,
createdAt: v.createdAt,
// Same contract as normalizeImage's renderMs above.
diff --git a/client/src/pages/VideoGen.jsx b/client/src/pages/VideoGen.jsx
index b20cc183df..ac7d7096bc 100644
--- a/client/src/pages/VideoGen.jsx
+++ b/client/src/pages/VideoGen.jsx
@@ -469,6 +469,11 @@ export default function VideoGen() {
const handleUpscaleHistory = useCallback((item) => {
setUpscaleItem(item?.raw || item);
}, []);
+ // A start trim is a new clip: list it first and open it in place of the source.
+ const handleTrimmed = useCallback((video) => {
+ setHistory((h) => [video, ...h]);
+ setPreview(normalizeVideo(video));
+ }, [setPreview]);
const handleUpscaled = useCallback((video) => {
setHistory((h) => [video, ...h]);
}, []);
@@ -1872,6 +1877,7 @@ export default function VideoGen() {
onPromptSaved={handlePromptSaved}
onContinue={handleContinue}
onRemix={(item) => item?.raw && handleRemixVideo(item.raw)}
+ onTrimmed={handleTrimmed}
/>
<GalleryImagePicker
diff --git a/client/src/services/apiImageVideo.js b/client/src/services/apiImageVideo.js
index b1b8e50c7f..9418617035 100644
--- a/client/src/services/apiImageVideo.js
+++ b/client/src/services/apiImageVideo.js
@@ -312,6 +312,12 @@ export const getUpscalePlan = (id, method, options = {}) => request(
// `/ic-loras/:key/download` route (issue #3100) already resolves for every
// registered IC-LoRA weight, remix mode or not.
export const upscaleAdapterDownloadUrl = (key) => (key ? `${API_BASE}/video-gen/ic-loras/${encodeURIComponent(key)}/download` : null);
+// Keep a clip from `startSec` on as a NEW gallery entry; the source stays as is.
+export const trimVideoStart = (id, startSec, options = {}) => request(`/video-gen/history/${encodeURIComponent(id)}/trim-start`, {
+ method: 'POST',
+ body: JSON.stringify({ startSec }),
+ ...options,
+});
export const stitchVideos = (videoIds, options = {}) => request('/video-gen/stitch', {
method: 'POST',
body: JSON.stringify({ videoIds }),
diff --git a/server/routes/videoGen.js b/server/routes/videoGen.js
index f6bf4a9fd0..a7caf2f9ee 100644
--- a/server/routes/videoGen.js
+++ b/server/routes/videoGen.js
@@ -55,6 +55,7 @@ import {
// re-declaring it just so this file's route schemas can be built.
import { UPSCALE_METHODS, DEFAULT_UPSCALE_METHOD } from '../services/videoGen/upscalePlan.js';
import { enqueueLtxUpscale } from '../services/videoGen/upscaleJob.js';
+import { trimHistoryItemStart } from '../services/videoGen/trimStart.js';
import { cleanupMultipartTemp } from '../services/videoGen/prepareParams.js';
import { submitVideoGenJob } from '../services/videoGen/submitJob.js';
import { resolveReactorApiKey, mintReactorToken } from '../services/videoGen/reactor.js';
@@ -1252,6 +1253,16 @@ router.post('/upscale/:id', asyncHandler(async (req, res) => {
res.json({ ok: true, video: entry });
}));
+// Keep a clip from a later frame on (a start trim). Like an upscale, it writes
+// a NEW gallery row and leaves the source clip untouched.
+const trimStartBodySchema = z.object({ startSec: z.number().finite().positive().max(3600) });
+router.post('/history/:id/trim-start', asyncHandler(async (req, res) => {
+ const parsed = historyIdSchema.safeParse(req.params.id);
+ if (!parsed.success) failValidation(parsed);
+ const body = validateRequest(trimStartBodySchema, req.body ?? {});
+ res.json({ ok: true, video: await trimHistoryItemStart(parsed.data, body) });
+}));
+
const stitchBodySchema = z.object({
videoIds: z.array(historyIdSchema).min(2).max(20),
});
diff --git a/server/routes/videoGen.test.js b/server/routes/videoGen.test.js
index 23f453289c..94786cdf21 100644
--- a/server/routes/videoGen.test.js
+++ b/server/routes/videoGen.test.js
@@ -110,6 +110,10 @@ vi.mock('../services/videoGen/upscaleJob.js', () => ({
enqueueLtxUpscale: vi.fn(),
}));
+vi.mock('../services/videoGen/trimStart.js', () => ({
+ trimHistoryItemStart: vi.fn(),
+}));
+
vi.mock('../services/videoGen/local.js', () => ({
// The route checks `runtime` on the default model when validating a2v —
// include it so the a2v happy-path tests don't trip the runtime capability
@@ -295,6 +299,7 @@ vi.mock('fs/promises', () => ({
import { copyFile, unlink } from 'fs/promises';
import * as videoGenService from '../services/videoGen/local.js';
import * as upscaleJobService from '../services/videoGen/upscaleJob.js';
+import { trimHistoryItemStart } from '../services/videoGen/trimStart.js';
import * as mediaJobQueue from '../services/mediaJobQueue/index.js';
import { prepareRemoteMediaJob } from '../services/federatedMedia/remoteSubmission.js';
import { getProject as getMusicVideoProject } from '../services/musicVideo/projects.js';
@@ -3056,6 +3061,26 @@ describe('videoGen routes', () => {
});
});
+ describe('POST /history/:id/trim-start', () => {
+ const id = 'aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaa1';
+
+ it('returns the new trimmed clip', async () => {
+ trimHistoryItemStart.mockResolvedValue({ id: 'new-clip', trimStartSec: 1.25 });
+ const r = await request(app).post(`/api/video-gen/history/${id}/trim-start`).send({ startSec: 1.25 });
+ expect(r.status).toBe(200);
+ expect(r.body.video).toEqual({ id: 'new-clip', trimStartSec: 1.25 });
+ expect(trimHistoryItemStart).toHaveBeenCalledWith(id, { startSec: 1.25 });
+ });
+
+ it('rejects a missing or non-positive start before trimming', async () => {
+ for (const body of [{}, { startSec: 0 }, { startSec: '2' }]) {
+ const r = await request(app).post(`/api/video-gen/history/${id}/trim-start`).send(body);
+ expect(r.status).toBe(400);
+ }
+ expect(trimHistoryItemStart).not.toHaveBeenCalled();
+ });
+ });
+
describe('POST /last-frame/:id', () => {
it('forwards a shared-gallery upload id to extractLastFrame', async () => {
const uploadId = 'upload-ab12cd34';
diff --git a/server/services/videoGen/conditioningMedia.js b/server/services/videoGen/conditioningMedia.js
index a938f442d8..c39c3c32a9 100644
--- a/server/services/videoGen/conditioningMedia.js
+++ b/server/services/videoGen/conditioningMedia.js
@@ -13,6 +13,15 @@ import { IC_STILL_REFERENCE_FRAMES } from './renderArgs.js';
const execFileAsync = promisify(execFile);
+// LTX-2.x was trained on video frames, so Lightricks' pipelines re-compress a
+// conditioning still through H.264 before encoding it (CRF 33 for LTX-2.0 to
+// 2.3, `DEFAULT_IMAGE_CRF` in ltx_pipelines). A pristine still is out of
+// distribution: the model holds it for the first frame and then cuts away to
+// a different scene. The dgrauet/MrMofer runtimes do this round trip in their
+// own loader; the notapalindrome `mlx_video.generate_av` CLI does not, so
+// PortOS does it here for that runtime.
+const CONDITIONING_CRF_BY_RUNTIME = Object.freeze({ mlx_video: 33 });
+
/** Resolve local conditioning media and return its existing cleanup capability.
* Derived files are always owned here; upload/audio cleanup stays caller-selected.
*/
@@ -78,6 +87,7 @@ export async function prepareVideoConditioningMedia({
}
const ffmpeg = (sourceImagePath || lastImageWillBeUsed || hasMultiKeyframes) ? await findFfmpeg() : null;
const ffprobe = model.runtime === 'minimax_h3_ref2va' ? await findFfprobe() : null;
+ const conditioningCrf = CONDITIONING_CRF_BY_RUNTIME[model.runtime || 'mlx_video'] ?? null;
const resizeImage = async (srcPath, tag) => {
if (!srcPath || !ffmpeg) return { resolved: srcPath, tempPath: null };
const resizedPath = join(tmpdir(), `resized-${tag}-${jobId}.png`);
@@ -91,6 +101,7 @@ export async function prepareVideoConditioningMedia({
console.log(`⚠️ Failed to resize ${tag} image, using original: ${resizeResult.error.message}`);
return { resolved: srcPath, tempPath: null };
}
+ if (conditioningCrf != null) await recompressAsVideoFrame(ffmpeg, resizedPath, conditioningCrf, `${tag}-${jobId}`);
return { resolved: resizedPath, tempPath: resizedPath };
};
// Two independent ffmpeg spawns — fan out for the same reason the keyframe
@@ -219,3 +230,19 @@ async function materializeIngredientsReferences({
return icReferencePaths;
}
+
+/** Round-trip a still through one H.264 frame at `crf`, in place (see CONDITIONING_CRF_BY_RUNTIME). */
+async function recompressAsVideoFrame(ffmpeg, pngPath, crf, tag) {
+ const framePath = join(tmpdir(), `crf-${tag}.mp4`);
+ const options = safeChildProcessOptions({ timeout: 10000 });
+ const failed = await execFileAsync(ffmpeg, [
+ '-i', pngPath, '-frames:v', '1', '-c:v', 'libx264', '-preset', 'veryfast', '-crf', String(crf),
+ '-pix_fmt', 'yuv420p', '-y', framePath,
+ ], options)
+ .then(() => execFileAsync(ffmpeg, ['-i', framePath, '-frames:v', '1', '-update', '1', '-y', pngPath], options))
+ .then(() => null, (err) => err);
+ await unlinkGuarded(framePath).catch(() => {});
+ // A still that keeps its pristine pixels is still a valid conditioning, so
+ // a failed round trip degrades to the old behavior rather than the render.
+ if (failed) console.warn(`⚠️ Could not re-compress the ${tag} conditioning frame: ${failed.message}`);
+}
diff --git a/server/services/videoGen/conditioningMedia.test.js b/server/services/videoGen/conditioningMedia.test.js
index 76ba80185a..b4f917224d 100644
--- a/server/services/videoGen/conditioningMedia.test.js
+++ b/server/services/videoGen/conditioningMedia.test.js
@@ -43,4 +43,35 @@ describe('prepareVideoConditioningMedia', () => {
expect(findFfmpegMock).not.toHaveBeenCalled();
expect(execFileMock).not.toHaveBeenCalled();
});
+
+ // Uniquely catches the LTX-2.3 "holds the reference for one frame, then cuts
+ // away" regression: the mlx_video CLI skips Lightricks' CRF round trip, so
+ // PortOS must do it, and only for that runtime (the others do their own).
+ const imageInput = (runtime) => ({
+ model: { runtime },
+ mode: 'image',
+ sourceImagePath: '/tmp/source.png',
+ w: 704,
+ h: 448,
+ parsedFps: 24,
+ jobId: `crf-${runtime}`,
+ uploadedTempPath: null,
+ uploadedTempPaths: [],
+ audioFilePath: null,
+ });
+ const crfCalls = () => execFileMock.mock.calls.filter(([, args]) => args.includes('-crf'));
+
+ it('re-compresses the conditioning still at CRF 33 on the mlx_video runtime', async () => {
+ const result = await prepareVideoConditioningMedia(imageInput('mlx_video'));
+ expect(crfCalls()).toHaveLength(1);
+ const [, args] = crfCalls()[0];
+ expect(args[args.indexOf('-crf') + 1]).toBe('33');
+ expect(args[args.indexOf('-i') + 1]).toBe(result.resolvedSourceImage);
+ });
+
+ it('leaves the still alone on runtimes whose loader already does the round trip', async () => {
+ await prepareVideoConditioningMedia(imageInput('ltx25'));
+ expect(execFileMock).toHaveBeenCalledTimes(1);
+ expect(crfCalls()).toHaveLength(0);
+ });
});
diff --git a/server/services/videoGen/trimStart.js b/server/services/videoGen/trimStart.js
new file mode 100644
index 0000000000..1a612db93c
--- /dev/null
+++ b/server/services/videoGen/trimStart.js
@@ -0,0 +1,90 @@
+/** Non-destructive start trim for video-history items: keep a clip from a later frame on. */
+
+import { join } from 'path';
+import { randomUUID } from 'crypto';
+import { PATHS } from '../../lib/fileUtils.js';
+import { ServerError } from '../../lib/errorHandler.js';
+import {
+ generateThumbnail, probeFrameCount, probeVideoStreamInfo, trimVideoFromFrame,
+} from '../../lib/ffmpeg.js';
+import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
+import { omitRenderTiming, renderTimingFields } from '../../lib/renderTiming.js';
+import { discardUnpublishedVideo } from './generateVideoHelpers.js';
+import { mutateVideoHistory } from './history.js';
+import { resolveHistoryItem, resolveSourcePath } from './upscaleVideo.js';
+
+// A trimmed copy shorter than this is not a usable clip.
+const MIN_KEPT_FRAMES = 2;
+
+// The clip's frame rate: the render's own `fps` when it recorded one, else the
+// stream's (uploads and older rows carry none).
+const resolveFps = async (item, sourcePath) => {
+ const recorded = Number(item.fps);
+ if (Number.isFinite(recorded) && recorded > 0) return recorded;
+ const probed = (await probeVideoStreamInfo(sourcePath))?.fps;
+ if (Number.isFinite(probed) && probed > 0) return probed;
+ throw new ServerError('Could not read the clip frame rate', { status: 422, code: 'FPS_UNKNOWN' });
+};
+
+// Copy history item `historyId` into a NEW gallery row that starts at
+// `startSec` (snapped to the nearest frame). The source clip is untouched, so
+// a trim the user regrets costs nothing. Returns the new history entry.
+export async function trimHistoryItemStart(historyId, { startSec } = {}) {
+ const item = await resolveHistoryItem(historyId);
+ const sourcePath = resolveSourcePath(item);
+ const start = Number(startSec);
+ if (!Number.isFinite(start) || start <= 0) {
+ throw new ServerError('startSec must be a positive number of seconds', { status: 400, code: 'VALIDATION_ERROR' });
+ }
+ const fps = await resolveFps(item, sourcePath);
+ const startFrame = Math.round(start * fps);
+ const totalFrames = await probeFrameCount(sourcePath);
+ if (startFrame < 1) {
+ throw new ServerError('That is already the first frame', { status: 400, code: 'TRIM_AT_START' });
+ }
+ if (Number.isFinite(totalFrames) && totalFrames - startFrame < MIN_KEPT_FRAMES) {
+ throw new ServerError('Pick a frame before the end of the clip', { status: 400, code: 'TRIM_PAST_END' });
+ }
+
+ const newId = randomUUID();
+ const newFilename = `${newId}.mp4`;
+ const newPath = join(PATHS.videos, newFilename);
+ const renderStartedAtMs = Date.now();
+ console.log(`✂️ Trimming video [${historyId.slice(0, 8)} → ${newId.slice(0, 8)}] from frame ${startFrame}`);
+ const result = await trimVideoFromFrame(sourcePath, newPath, { startFrame, fps });
+ if (!result.ok) {
+ await discardUnpublishedVideo({ jobId: newId, outputPath: newPath });
+ throw new ServerError(`Trim failed: ${result.reason}`, { status: 500, code: 'FFMPEG_FAILED' });
+ }
+ return withBackupAssetPublication(async () => {
+ let committed = false;
+ try {
+ const thumbnail = await generateThumbnail(newPath, newId);
+ const keptFrames = await probeFrameCount(newPath);
+ const trimStartSec = Math.round((startFrame / fps) * 1000) / 1000;
+ const newEntry = {
+ ...omitRenderTiming(item),
+ id: newId,
+ filename: newFilename,
+ thumbnail,
+ createdAt: new Date().toISOString(),
+ ...(Number.isFinite(keptFrames) ? { numFrames: keptFrames } : {}),
+ fps,
+ // A poster picked on the source points into the cut-away part.
+ posterSec: undefined,
+ trimmedFrom: item.id,
+ trimStartFrame: startFrame,
+ trimStartSec,
+ hidden: false,
+ ...renderTimingFields(renderStartedAtMs),
+ };
+ await mutateVideoHistory((history) => { history.unshift(newEntry); return history; });
+ committed = true;
+ console.log(`✅ Trimmed [${newId.slice(0, 8)}]: ${newFilename} starts at ${trimStartSec}s`);
+ return newEntry;
+ } catch (error) {
+ if (!committed) await discardUnpublishedVideo({ jobId: newId, outputPath: newPath });
+ throw error;
+ }
+ });
+}
diff --git a/server/services/videoGen/trimStart.test.js b/server/services/videoGen/trimStart.test.js
new file mode 100644
index 0000000000..737a8aabb4
--- /dev/null
+++ b/server/services/videoGen/trimStart.test.js
@@ -0,0 +1,61 @@
+import { describe, it, expect, beforeEach, afterAll, vi } from 'vitest';
+import { execFileSync } from 'child_process';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { makePathsProxy, lazyTempDataRoot, cleanupTempDataRoots } from '../../lib/mockPathsDataRoot.js';
+
+// Real files under a temp data root: the trim writes a new clip and a history
+// row, and the install's data/ is the developer's live gallery.
+vi.mock('../../lib/fileUtils.js', async (importOriginal) =>
+ makePathsProxy(await importOriginal(), { dataRoot: () => lazyTempDataRoot('portos-trim-start-') }));
+afterAll(cleanupTempDataRoots);
+
+const hasFfmpeg = (() => {
+ try {
+ execFileSync('ffmpeg', ['-version'], { stdio: 'ignore' });
+ execFileSync('ffprobe', ['-version'], { stdio: 'ignore' });
+ return true;
+ } catch { return false; }
+})();
+
+const { trimHistoryItemStart } = await import('./trimStart.js');
+const { loadHistory, mutateVideoHistory } = await import('./history.js');
+const { PATHS } = await import('../../lib/fileUtils.js');
+const { probeFrameCount } = await import('../../lib/ffmpeg.js');
+
+const SOURCE_ID = '22222222-2222-4222-8222-222222222222';
+
+describe.skipIf(!hasFfmpeg)('trimHistoryItemStart (real ffmpeg)', () => {
+ beforeEach(async () => {
+ mkdirSync(PATHS.videos, { recursive: true });
+ // 2 s at 24 fps = 48 frames.
+ execFileSync('ffmpeg', ['-y', '-v', 'error', '-f', 'lavfi', '-i', 'testsrc=size=64x64:rate=24:duration=2',
+ '-pix_fmt', 'yuv420p', join(PATHS.videos, `${SOURCE_ID}.mp4`)]);
+ writeFileSync(join(PATHS.data, 'video-history.json'), '[]');
+ await mutateVideoHistory(() => [{
+ id: SOURCE_ID, filename: `${SOURCE_ID}.mp4`, prompt: 'a lighthouse', modelId: 'ltx23_distilled_q4',
+ width: 64, height: 64, numFrames: 48, fps: 24, posterSec: 0.2, renderMs: 90000,
+ }]);
+ });
+
+ // Uniquely catches a trim that edits the source in place, keeps the wrong
+ // frames, or leaves the new clip out of the gallery.
+ it('writes a new gallery clip from the chosen frame and leaves the source intact', async () => {
+ const entry = await trimHistoryItemStart(SOURCE_ID, { startSec: 0.5 });
+ expect(entry).toMatchObject({
+ trimmedFrom: SOURCE_ID, trimStartFrame: 12, trimStartSec: 0.5, numFrames: 36, fps: 24, prompt: 'a lighthouse',
+ });
+ expect(entry.id).not.toBe(SOURCE_ID);
+ expect(entry.posterSec).toBeUndefined();
+ expect(await probeFrameCount(join(PATHS.videos, entry.filename))).toBe(36);
+ expect(await probeFrameCount(join(PATHS.videos, `${SOURCE_ID}.mp4`))).toBe(48);
+ const history = await loadHistory();
+ expect(history.map((h) => h.id)).toEqual([entry.id, SOURCE_ID]);
+ });
+
+ it('refuses a start at the first frame or past the end, writing nothing', async () => {
+ await expect(trimHistoryItemStart(SOURCE_ID, { startSec: 0.01 })).rejects.toMatchObject({ code: 'TRIM_AT_START' });
+ await expect(trimHistoryItemStart(SOURCE_ID, { startSec: 1.99 })).rejects.toMatchObject({ code: 'TRIM_PAST_END' });
+ expect((await loadHistory()).map((h) => h.id)).toEqual([SOURCE_ID]);
+ });
+});
diff --git a/server/services/videoGen/upscaleVideo.js b/server/services/videoGen/upscaleVideo.js
index 6805603cd4..0c5cf4d663 100644
--- a/server/services/videoGen/upscaleVideo.js
+++ b/server/services/videoGen/upscaleVideo.js
@@ -49,7 +49,7 @@ const resolveMethod = (options) => {
// shape. Validating the arg first surfaces a clean 400 even if the history file
// happens to contain a record with a malformed id, and it short-circuits the
// loadHistory I/O for obviously-bogus requests.
-const resolveHistoryItem = async (historyId) => {
+export const resolveHistoryItem = async (historyId) => {
if (typeof historyId !== 'string' || (!UUID_RE.test(historyId) && !UPLOADED_HISTORY_ID_RE.test(historyId))) {
throw new ServerError('Invalid history id', { status: 400, code: 'VALIDATION_ERROR' });
}
@@ -59,7 +59,7 @@ const resolveHistoryItem = async (historyId) => {
return item;
};
-const resolveSourcePath = (item) => {
+export const resolveSourcePath = (item) => {
const sourcePath = safeUnder(PATHS.videos, item.filename);
if (!sourcePath) throw new ServerError('Invalid video filename', { status: 400, code: 'VALIDATION_ERROR' });
if (!existsSync(sourcePath)) throw new ServerError('Video file not found on disk', { status: 404, code: 'NOT_FOUND' });