Skip to content

fix(nodes): let a transcode node be pinned to VideoToolbox - #4940

Open
Quick104 wants to merge 3 commits into
mainfrom
fix/node-videotoolbox-override
Open

Quick104 wants to merge 3 commits into
mainfrom
fix/node-videotoolbox-override

Conversation

@Quick104

@Quick104 Quick104 commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Related issue: #1175
Validation tasks: unblocks #1175 C2; changes #1178 C1

Other clients: N/A (web admin and server only; the native apps have no node editor)

A Mac transcode node can't be pinned to VideoToolbox. Starting one with SILO_NODE_HW_ACCEL=videotoolbox stops it at startup with SILO_NODE_HW_ACCEL hw_accel_override must be one of auto, qsv, vaapi, nvenc, none, and the Hardware Acceleration list in the node editor has no VideoToolbox entry. The cluster-wide playback.hw_accel setting already accepts videotoolbox, so the per-node override was the only place that refused it. On a Mac node the editor also asks for Linux render-device paths (/dev/dri/...), which mean nothing there.

auto already resolves VideoToolbox on a Mac, so this mostly matters in a cluster whose cluster-wide setting names another backend, and for the forced mode #1175 C2 asks to test on a node.

Approach

videotoolbox joins the per-node override everywhere the value is checked: hwAccelOverrideValues, the node registration enum (regenerated into contracts/api/v2/openapi.json), and the stream_nodes.hw_accel_override check constraint, through a new migration. Its down step returns a VideoToolbox pin to inheriting and drops the field's environment lock. The node editor lists VideoToolbox and hides the GPU devices field when the node will run VideoToolbox: pinned, inherited from the cluster, or resolved by the node itself under Auto. The existing CUDA-device check and the new one share one helper that works out which backend the node runs. docs/admin-api.md lists the new value, and videotoolbox as a resolved and detected backend, which the macOS probe already reported.

Validation

  • Tested live on an Apple M4 Mac mini with the server in Docker Desktop and a native transcode node, on a local image of this branch merged with its two companion branches.
  • A node started with SILO_NODE_HW_ACCEL=videotoolbox registers, and the server records the field as declared by the node.
  • Pinning VideoToolbox in the editor saves. New transcodes use h264_videotoolbox and scale_vt within a minute, with no node restart. Re-probe hardware updates the node's reported backend.
  • The migration applied to an existing database; its down step on a scratch database cleared the pin and the lock, before and after the down step took the table lock first.
  • TestNodeDeclarationsLockFieldsDB fails on the unmigrated database (violates check constraint "stream_nodes_hw_accel_override_check") and passes after. The nodedeclare env test fails on the base with the startup error above and passes after.
  • Go build, vet and tests for the touched packages, make lint-changed, make verify-apiv2-openapi, verify-apiv2-web-types, verify-apiv2-contract, migrate-validate and verify-migrations pass. Web lint, typecheck and the src/pages tests pass.
  • make verify-route-inventory can't type-check the Linux cgo packages on macOS; CI runs it.

Evidence

Evidence: https://evidence.siloserver.org/r/silo-server/node-videotoolbox-override/

Surface and build: web admin, desktop and phone width; before on published build 2673 · 262ac3d, after on a local image of this branch.

Risks

  • During a rolling upgrade, an API replica still on the old binary rejects videotoolbox until it updates, and a node that declares SILO_NODE_HW_ACCEL=videotoolbox stops at startup if such a replica answers its registration. Upgrade every API server before setting it on a node, and remove it from nodes before rolling the servers back.
  • Rolling the migration back returns VideoToolbox pins to inheriting the cluster setting.

Follow-ups

Checklist

  • I read and can explain the complete diff.
  • This pull request addresses one concern.
  • Each test this pull request adds meets "Decide what to test" in CONTRIBUTING.md.
  • The Evidence section shows every change a user can see, or how I checked a change nobody sees.

Council review

Plan round: Sol (gpt-6.2-sol, xhigh) and Opus (claude-opus-5-5, high). Gemini (gemini-4-neon) was unavailable: this session doesn't run in full access.

Rounds: 1, last reviewed 58ae25f; fixes in 52dd39f

Member Round 1
Sol (gpt-6.2-sol, xhigh) 7/10, not posted on the PR: the down step's UPDATE ran before the table lock its ALTERs need, so it could deadlock with a node health write (fixed: the lock comes first); a node declaring videotoolbox stops at startup against an old API replica (upgrade order now under Risks); the SwiftPM cache files (removed). Dismissed: switching from NVENC to VideoToolbox clears a CUDA device, as any change of device syntax already does; the editor reads a stale resolved backend under Auto only after a node was pinned to a backend its host can't run, as it already does for NVENC.
Opus (claude-opus-5-5, high) 8/10: two SwiftPM cache files committed by mistake (removed); docs/admin-api.md didn't list videotoolbox as a resolved or detected backend (fixed)
Gemini (gemini-4-neon, xhigh) unavailable

Visual review: 1 round, captures from a local image at 79209d69

Member Round 1
Sol better, 8/10
Opus better, 8/10
Gemini unavailable

Answered: the Source access field looks different between the captures because the two nodes were set up differently (environment-declared before, Admin > Nodes after); the Save button showing under the open list is how the list component already draws.

AI Disclosure

  • Harness: Claude Code in T3 Code
  • Tool(s): Claude Code, T3 Code delegate tasks, Codex CLI
  • Model(s): claude-opus-5-5 (orchestration, review), claude-opus-5 subagent (implementation), gpt-6.2-sol (plan and visual review)
  • Involvement: Fully AI-generated, human verified
  • Adversarial review: a plan round (Sol and Opus; Gemini unavailable) added the migration and the device-field change; an xhigh code review found the down step's leftover lock, and the background review the down step's lock order and the rolling-upgrade order; all fixed. See Council review.

🤖 Generated with Claude Code

Note

Allow transcode nodes to be pinned to videotoolbox acceleration

  • Adds videotoolbox as an accepted hw_accel_override value across the stack: OpenAPI contract, nodepool permitted values, a DB check-constraint migration, and admin UI options.
  • A new nodeBackend helper in adminNodesPresentation.ts resolves the effective backend (explicit override, inherited cluster backend, or node-reported value), and nodeUsesVideoToolbox hides the device-override control in the node form when it resolves to VideoToolbox.
  • Risk: the migration Down path in 20261121042328_allow_videotoolbox_node_override.sql takes an exclusive table lock and clears videotoolbox overrides (setting hw_accel_override to NULL and removing it from env_managed). Also, the admin form hides but does not clear the device-override value when VideoToolbox is selected.

Macroscope summarized 52dd39f.

A Mac transcode node started with SILO_NODE_HW_ACCEL=videotoolbox refused to
start, and the node editor offered no VideoToolbox choice, although the
cluster-wide playback.hw_accel accepts it. Allow videotoolbox in the per-node
override (validator, registration enum, stream_nodes check constraint) and the
editor, and hide the render-device field for a node that runs VideoToolbox.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@silo-triage silo-triage Bot added the size/L 200–499 added + deleted lines (all files); change volume, not priority. label Nov 21, 2026
@coderabbitai

coderabbitai Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

  • Ask an admin to enable usage-based reviews

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Next included review available in 10 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 4 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: c4a122e1-fadd-4d8b-82b2-43f9f6562204
Commits

Reviewing files that changed from the base of the PR and between 980e455 and 52dd39f.

Files selected for processing: 10

  • contracts/api/v2/openapi.json
  • docs/admin-api.md
  • internal/nodecontrol/protocol.go
  • internal/nodedeclare/nodedeclare_test.go
  • internal/nodepool/declaration_db_test.go
  • internal/nodepool/repository.go
  • migrations/sql/20261121042328_allow_videotoolbox_node_override.sql
  • web/src/pages/AdminNodes.tsx
  • web/src/pages/adminNodesPresentation.test.ts
  • web/src/pages/adminNodesPresentation.ts
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-21T06:28:19.263058Z 52dd39f New commits
🔒 Security Review ✅ Completed 2026-11-21T06:30:18.764728Z 52dd39f New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@silo-kody

silo-kody Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

Comment on lines +1059 to +1061
// VideoToolbox takes no device, so its control is hidden. The value stays in
// state and is saved as it was: hiding it clears nothing.
const showDeviceOverride = !nodeUsesVideoToolbox(node, hwAccelOverride, clusterHWAccel);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Bug medium

Selecting VideoToolbox silently clears an NVENC device override

Saving after switching from NVENC to VideoToolbox silently loses the hidden CUDA device override. Update selectHWAccelOverride to preserve the device when transitioning to or from VideoToolbox.

Prompt for LLM
File web/src/pages/AdminNodes.tsx, lines 1059-1061:

Selecting VideoToolbox silently clears an NVENC device override

Switching a node from NVENC to VideoToolbox clears its existing CUDA device override through `selectHWAccelOverride`, so saving the form silently loses the setting even though the hidden field is supposed to be preserved. Exclude transitions to and from VideoToolbox from device-syntax clearing so that the saved device remains available when switching back.

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Leaving this as it is. Moving from NVENC to VideoToolbox changes the device syntax, the same as moving from NVENC to QSV, which already clears the CUDA device. A VideoToolbox node takes no device, so saving null is right for that node. If the CUDA index were kept, it would carry into the next backend picked after VideoToolbox, such as VAAPI, where it means nothing. The comment on showDeviceOverride covers hiding the field without changing the selection, as for a Mac on Auto, and that clears nothing.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. Clearing the CUDA device override when switching from NVENC to VideoToolbox is consistent with the existing behavior for backend changes and avoids carrying an incompatible value into a later selection.

The showDeviceOverride comment describes a separate case: hiding the field without changing the selection preserves its value. I withdraw the suggestion; no change is needed.

@silo-triage silo-triage Bot added bug Something isn't working impact: compat Breaks a supported client or server path priority: P2 Limited scope, workaround exists, or polish labels Nov 21, 2026

@Quick104 Quick104 left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adversarial review (claude-opus-5-5, reviewed 58ae25f)

I checked the override end to end: the validator and hwAccelOverrideValues, the Registration enum and the OpenAPI schema it generates, the new Goose migration against the original inline CHECK (Postgres names it stream_nodes_hw_accel_override_check, so the DROP matches), the down step against env_managed, every EffectiveHWAccel caller (native playback, rehome, downloads, jellycompat, nodecontrol), node declaration from SILO_NODE_HW_ACCEL, and the editor's nodeBackend refactor. The backend side holds up. EffectiveHWAccel passes the override through verbatim, and the cluster setting already accepts videotoolbox, so every dispatch path already handled the value. The nodeUsesCUDADevices refactor keeps its earlier behaviour, and hwDeviceSyntaxChanges still only fires on the CUDA/render-path boundary. Rolling upgrade: until every API replica runs this build, a replica on the old build rejects a node that declares videotoolbox and rejects a full-form save that restates it. The new code has to deploy before anyone uses the value, which is the usual order and needs no fix.

F1 (should): stray SwiftPM build cache committed. Inline below.

F2 (nit, pre-existing, outside the diff): docs/admin-api.md still says resolved is never videotoolbox. The hardware report table gives resolved as nvenc, qsv, vaapi, or none, and detected_backends[].backend as nvenc, qsv, or vaapi. On macOS, DetectHWAccelWithFFmpegContextResult in internal/playback/gpudetect.go sets resolved to videotoolbox and adds a videotoolbox detected entry. The new nodeUsesVideoToolbox depends on exactly that value when a Mac node inherits an auto cluster. Since this PR already updates the override lists in the same doc, add videotoolbox to both tables there too.

Score: 8/10 as it stands. Once F1 is fixed it is a small, correct widening of an enum that the cluster setting already supports.

AI disclosure: written by Claude Code (model claude-opus-5-5) as an adversarial review of the pinned head 58ae25f. It read the diff and the surrounding source at that commit. It ran no builds or tests and did not read the PR description's evidence, comments, or other reviews. A person directed the review.

Comment thread .build/CACHEDIR.TAG Resolved
Drop two SwiftPM cache files committed by mistake.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s update

Taken after the UPDATE, the ALTERs' table lock could deadlock with a node's
health write waiting on an updated row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@silo-kody

silo-kody Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌
⚠️ 4 Kody Rule(s) were not evaluated

These rules declare that they need repository context beyond this diff, and the review could not retrieve it, so they were not judged on this pull request:

  • Preserve optional store capabilities through production wrappers
  • Detach mandatory cleanup from request cancellation and bound its lifetime
  • Preserve durable media identity and share identity-evidence precedence
  • Bound decoder throughput trades and share direct-play eligibility

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working impact: compat Breaks a supported client or server path priority: P2 Limited scope, workaround exists, or polish size/L 200–499 added + deleted lines (all files); change volume, not priority.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant