feat(transcode): add multi-resolution strategy with configurable ladders and fallback (#438)

* feat(transcode): add multi-resolution strategy with configurable ladders and fallback

* feat(settings): show toast on settings update and add manual verification plan to PR template

* fix(webui): preserve video resolution and fix 480p label in download dropdowns

* fix(webui): display standard short-side resolution for vertical videos in seekbar

* fix(webui): fix portrait transcode resolution labeling and serialize settings toggles
This commit is contained in:
Yiling-J
2026-10-01 13:27:50 +08:00
committed by GitHub
parent a84da8678e
commit e007054f47
35 changed files with 1260 additions and 123 deletions
@@ -43,10 +43,14 @@ describe('transcode-utils', () => {
expect(res).toEqual(['1080p', '720p', '480p'])
})
it('returns empty array when source is smaller than smallest ladder', () => {
// 640x360 source is smaller than 480p (854 long side)
it('falls back to lowest selected ladder when source is smaller than smallest ladder', () => {
// 640x360 source is smaller than 480p (854 long side) -> falls back to lowest selected (480p)
const res = getTargetHlsResolutions(undefined, 640, 360)
expect(res).toEqual([])
expect(res).toEqual(['480p'])
// When user selected 720p and 1440p, and source is 480p (854 long side) -> falls back to lowest selected (720p)
const resCustom = getTargetHlsResolutions(['720p', '1440p'], 854, 480)
expect(resCustom).toEqual(['720p'])
})
it('respects selective subset of configured ladders', () => {
@@ -79,9 +83,82 @@ describe('transcode-utils', () => {
})
describe('getTargetVideoResolutions', () => {
it('returns best match resolution for standard video', () => {
const resolutions = getTargetVideoResolutions('best_match', 1920, 1080)
expect(resolutions).toEqual(['180p', '1080p'])
describe('best_match strategy', () => {
it('returns best match resolution for 4K video', () => {
const resolutions = getTargetVideoResolutions('best_match', 3840, 2160)
expect(resolutions).toEqual(['180p', '2160p'])
})
it('returns best match resolution for 1080p video', () => {
const resolutions = getTargetVideoResolutions('best_match', 1920, 1080)
expect(resolutions).toEqual(['180p', '1080p'])
})
it('returns best match resolution for 720p video', () => {
const resolutions = getTargetVideoResolutions('best_match', 1280, 720)
expect(resolutions).toEqual(['180p', '720p'])
})
it('falls back to 480p for smaller videos (460p and 230p)', () => {
const res460 = getTargetVideoResolutions('best_match', 818, 460)
expect(res460).toEqual(['180p', '480p'])
const res230 = getTargetVideoResolutions('best_match', 408, 230)
expect(res230).toEqual(['180p', '480p'])
})
})
describe('multi strategy', () => {
it('returns all supported resolutions up to source for 4K video', () => {
const resolutions = getTargetVideoResolutions('multi', 3840, 2160)
expect(resolutions).toEqual(['180p', '2160p', '1440p', '1080p', '720p', '480p'])
})
it('returns resolutions up to 720p for 1280x720 video', () => {
const resolutions = getTargetVideoResolutions('multi', 1280, 720)
expect(resolutions).toEqual(['180p', '720p', '480p'])
})
it('returns resolutions up to 1080p for 2276x1280 video', () => {
const resolutions = getTargetVideoResolutions('multi', 2276, 1280)
expect(resolutions).toEqual(['180p', '1080p', '720p', '480p'])
})
it('falls back to lowest selected resolution (480p) for 460p and 230p videos', () => {
const res460 = getTargetVideoResolutions('multi', 818, 460)
expect(res460).toEqual(['180p', '480p'])
const res230 = getTargetVideoResolutions('multi', 408, 230)
expect(res230).toEqual(['180p', '480p'])
})
it('respects user-selected ladders and falls back to lowest selected ladder', () => {
const customLadders = ['720p', '1440p', '2160p'] as PrismaJson.VideoResolutionLadder[]
// 4K video: matches 2160p, 1440p, 720p (1080p was not selected)
const res4k = getTargetVideoResolutions('multi', 3840, 2160, customLadders)
expect(res4k).toEqual(['180p', '2160p', '1440p', '720p'])
// 230p video: nothing matches <= 408 -> falls back to lowest selected (720p)
const res230 = getTargetVideoResolutions('multi', 408, 230, customLadders)
expect(res230).toEqual(['180p', '720p'])
})
it('normalizes legacy "all" and "full" strategy values to multi', () => {
const resAll = getTargetVideoResolutions(
'all' as unknown as PrismaJson.VideoTranscodeStrategy,
1280,
720,
)
expect(resAll).toEqual(['180p', '720p', '480p'])
const resFull = getTargetVideoResolutions(
'full' as unknown as PrismaJson.VideoTranscodeStrategy,
1280,
720,
)
expect(resFull).toEqual(['180p', '720p', '480p'])
})
})
})
@@ -30,6 +30,35 @@ export const HLS_LADDER_ORDER: PrismaJson.HlsResolutionLadder[] = [
'480p',
]
export const VIDEO_LADDER_ORDER: PrismaJson.VideoResolutionLadder[] = [
'2160p',
'1440p',
'1080p',
'720p',
'480p',
]
export function matchResolutionsByLongSide<T extends string>(
selectedLadders: T[],
ladderOrder: T[],
rawLongSide: number,
): T[] {
const orderedSelected = ladderOrder.filter((ladder) => selectedLadders.includes(ladder))
if (orderedSelected.length === 0) return []
const matched = orderedSelected.filter((ladder) => {
const targetLongSide = RESOLUTION_LONG_SIDES[ladder]
return targetLongSide !== undefined && targetLongSide <= rawLongSide
})
if (matched.length === 0) {
// Falls back to the lowest resolution selected if nothing matched
return [orderedSelected[orderedSelected.length - 1]]
}
return matched
}
export function getTargetHlsResolutions(
configuredLadders: PrismaJson.HlsResolutionLadder[] | undefined,
originalWidth: number,
@@ -42,11 +71,7 @@ export function getTargetHlsResolutions(
const rawLongSide = Math.max(originalWidth, originalHeight)
return HLS_LADDER_ORDER.filter((ladder) => {
if (!selectedLadders.includes(ladder)) return false
const targetLongSide = RESOLUTION_LONG_SIDES[ladder]
return targetLongSide <= rawLongSide
})
return matchResolutionsByLongSide(selectedLadders, HLS_LADDER_ORDER, rawLongSide)
}
export function resolutionToDimensions(
@@ -74,31 +99,11 @@ export function resolutionToDimensions(
return [width, height]
}
const TARGET_RESOLUTIONS = [
{ name: '2160p', longSide: 3840 },
{ name: '1080p', longSide: 1920 },
{ name: '720p', longSide: 1280 },
{ name: '540p', longSide: 960 },
{ name: '360p', longSide: 640 },
]
function getBestMatchResolution(
originalWidth: number,
originalHeight: number,
): { name: string; longSide: number } {
const rawLongSide = Math.max(originalWidth, originalHeight)
const lower = TARGET_RESOLUTIONS.filter((r) => r.longSide <= rawLongSide)
if (lower.length > 0) {
lower.sort((a, b) => b.longSide - a.longSide)
return lower[0]
}
return TARGET_RESOLUTIONS[TARGET_RESOLUTIONS.length - 1]
}
export function getTargetVideoResolutions(
strategy: PrismaJson.VideoTranscodeStrategy,
originalWidth: number,
originalHeight: number,
configuredResolutions?: PrismaJson.VideoResolutionLadder[],
): string[] {
const resolutions = ['180p']
@@ -106,21 +111,27 @@ export function getTargetVideoResolutions(
const stratStr = strategy as string
if (stratStr === 'single' || stratStr === 'disable') {
normalizedStrategy = 'best_match'
} else if (stratStr === 'full') {
normalizedStrategy = 'all'
} else if (stratStr === 'full' || stratStr === 'all' || stratStr === 'multi') {
normalizedStrategy = 'multi'
}
const bestMatch = getBestMatchResolution(originalWidth, originalHeight)
const selectedLadders =
configuredResolutions && configuredResolutions.length > 0
? configuredResolutions
: (['480p', '720p', '1080p', '1440p', '2160p'] as PrismaJson.VideoResolutionLadder[])
const rawLongSide = Math.max(originalWidth, originalHeight)
if (normalizedStrategy === 'best_match') {
resolutions.push(bestMatch.name)
} else if (normalizedStrategy === 'all') {
const bestMatchIndex = TARGET_RESOLUTIONS.findIndex((r) => r.name === bestMatch.name)
if (bestMatchIndex !== -1) {
for (let i = bestMatchIndex; i < TARGET_RESOLUTIONS.length; i++) {
resolutions.push(TARGET_RESOLUTIONS[i].name)
}
}
const matched = matchResolutionsByLongSide(
['480p', '720p', '1080p', '1440p', '2160p'] as PrismaJson.VideoResolutionLadder[],
VIDEO_LADDER_ORDER,
rawLongSide,
)
resolutions.push(matched[0])
} else if (normalizedStrategy === 'multi') {
const matched = matchResolutionsByLongSide(selectedLadders, VIDEO_LADDER_ORDER, rawLongSide)
resolutions.push(...matched)
}
return resolutions
@@ -796,4 +796,82 @@ describe('transcodeVideoWorkflow', () => {
status: WorkflowTaskStatus.completed,
})
})
it('should transcode selected multi resolutions when videoStrategy is multi', () => {
const task: WorkflowTask = {
id: 'task-multi',
assetId: 'asset-multi',
type: WorkflowTaskType.transcode_video,
status: WorkflowTaskStatus.pending,
sessionId: null,
output: null,
payload: {
projectId: 'proj-1',
transcode: {
videoStrategy: 'multi',
videoResolutions: ['720p', '1080p', '2160p'],
},
},
createdAt: new Date(),
updatedAt: new Date(),
heartbeat: null,
teamId: 'team-1',
projectId: 'proj-1',
uid: 'task-uid',
model: null,
inputTokens: 0,
outputTokens: 0,
}
mockActivities.getAssetActivity.mockResolvedValue({
id: 'asset-multi',
storageKey: { key: 'files/asset-multi/video.mp4' },
mediaType: 'video/mp4',
})
mockActivities.getMediaInfoActivity.mockResolvedValue({
proxyType: 'video',
metadata: {
originalWidth: 1920,
originalHeight: 1080,
duration: 10,
frameRate: 30,
totalFrames: 300,
startTimecode: '00:00:00:00',
bitRate: 1000,
hasAudio: false,
format: {},
},
videoTranscodes: [],
imageTranscodes: [],
})
mockActivities.transcodeVideoActivity.mockImplementation(async (params) => ({
key: `files/asset-multi/${params.videoSpec.resolution}.mp4`,
width: params.videoSpec.width,
height: params.videoSpec.height,
resolution: params.videoSpec.resolution,
}))
return transcodeVideoWorkflow(task).then(() => {
// 180p preview + 1080p + 720p (2160p is skipped since > 1920)
expect(mockActivities.transcodeVideoActivity).toHaveBeenCalledTimes(3)
expect(mockActivities.transcodeVideoActivity).toHaveBeenCalledWith(
expect.objectContaining({
videoSpec: expect.objectContaining({ resolution: '180p' }),
}),
)
expect(mockActivities.transcodeVideoActivity).toHaveBeenCalledWith(
expect.objectContaining({
videoSpec: expect.objectContaining({ resolution: '1080p' }),
}),
)
expect(mockActivities.transcodeVideoActivity).toHaveBeenCalledWith(
expect.objectContaining({
videoSpec: expect.objectContaining({ resolution: '720p' }),
}),
)
})
})
})
@@ -129,6 +129,7 @@ export async function transcodeVideoWorkflow(task: WorkflowTask): Promise<void>
spec.videoStrategy || 'best_match',
metadata.originalWidth,
metadata.originalHeight,
spec.videoResolutions,
)
for (const res of videoResolutions) {
const [width, height] = resolutionToDimensions(