## Summary
- Add "Make Public" / "Make Private" button on completed job cards
allowing users to toggle visibility
- Two distinct backend flows: Public→Private (fast redistribution ~1-2
min) and Private→Public (full re-processing ~15-30 min)
- Confirmation modal with direction-specific explanations of what will
happen
## Changes
### Backend
- **New service:** `visibility_change_service.py` — validation, two
change flows, distributed output cleanup (YouTube/Dropbox/GDrive/GCS),
brand code recycling
- **New endpoint:** `POST /api/jobs/{job_id}/change-visibility` with
proper 404/403/400 status codes
- **Video worker:** Added `redistribute_video()` for fast public→private
path (reuses existing finals)
- **Screens worker:** Added render worker trigger after screen regen for
private→public pipeline
- **State machine:** Added `COMPLETE → LYRICS_COMPLETE` transition for
re-processing flow
- **Version:** 0.135.2 → 0.136.0
### Frontend
- **OutputLinks:** "Make Public"/"Make Private" button with Lock/Globe
icons
- **AlertDialog:** Confirmation modal with direction-specific content
explaining consequences
- **API client:** `changeVisibility()` method and response type
### Tests
- 22 backend tests: validation (11), change_to_private (3),
change_to_public (3), output cleanup (4), state transitions (1)
- Frontend OutputLinks test updated for new visibility button
## Testing
- [x] All 22 new backend tests pass
- [x] 2164/2165 backend tests pass (1 pre-existing failure unrelated)
- [x] 573/573 frontend tests pass (30 suites)
## Review
- [x] CodeRabbit CLI review completed locally
- [x] Fixed: Dropbox folder name sanitization mismatch
- [x] Fixed: HTTP status codes (404 for missing job, 403 for ownership)
- [x] Skipped: Screens worker direct DB update (acceptable for simple
restore)
@coderabbitai ignore
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
15 KiB
Change Visibility Plan
Date: 2026-03-06 Branch:
feat/sess-20260306-1750-change-visibilityStatus: Draft
Problem
Users who accidentally select the wrong visibility (public/private) during job creation have no way to change it after the job completes. Currently, only admins can toggle is_private via the PATCH endpoint, and when toggling to private it only auto-deletes outputs -- it doesn't re-distribute to the correct destination.
Example: Job fdcc82a6 was accidentally created as private but should be public.
Requirements
- Any user who can see a job (creator or admin) can change visibility on completed jobs
- A confirmation modal explains exactly what will happen before proceeding
- Modal wording varies based on direction (public->private vs private->public)
- Tenant jobs (Vocal Star, Singa) are excluded -- this is consumer gen only
- No cooldown/rate limiting needed
Two Distinct Flows
Flow A: Public -> Private (simpler, faster)
The video content doesn't change -- same nomad theme, same screens. We just need to move outputs from public destinations to private ones.
Steps:
- Delete distributed outputs (YouTube, Dropbox
/Tracks-Organized/, GDrive) but keep GCS finals - Recycle the NOMAD brand code
- Set
is_private = trueon the job - Re-run distribution only: allocate NOMADNP brand code, upload finals to Dropbox
/Tracks-NonPublished/ - Update job state_data with new brand_code and dropbox_link
- Clear
outputs_deleted_atflag - Mark job as complete
Expected duration: ~1-2 minutes (just file uploads)
Flow B: Private -> Public (complex, slower)
Private jobs may have custom styles (backgrounds, colors) that don't conform to the public Nomad branding. We must reset to defaults and re-process from screens onward.
Steps:
- Delete distributed outputs (Dropbox
/Tracks-NonPublished/) + delete GCS finals + delete screens + deletewith_vocals.mkv - Recycle the NOMADNP brand code
- Permanently clear custom style data:
- Reset
theme_idto"nomad"(or whatever the default is) - Clear
color_overridesto{} - Clear
style_assetsto{} - Delete any custom style files from GCS (
jobs/{job_id}/style/)
- Reset
- Set
is_private = falseon the job - Set job status to
LYRICS_COMPLETE(entry point for screens worker) - Clear relevant progress keys:
screens_progress,render_progress,video_progress,encoding_progress - Trigger screens worker, which cascades through: screens -> awaiting_review (auto-skip, since review is already done) -> render -> encode -> distribute publicly
- Job returns to
COMPLETEwith public outputs (YouTube, Dropbox/Tracks-Organized/, GDrive)
Expected duration: ~15-30 minutes (re-render + re-encode + distribute)
Key gotcha: After regenerating screens, the pipeline normally transitions to AWAITING_REVIEW. But we've already completed review -- we need to auto-skip review and proceed to rendering. We'll use a regen_restore_status mechanism (already exists for the regenerate-screens endpoint) to signal the screens worker to restore to REVIEW_COMPLETE instead of AWAITING_REVIEW, which triggers the render worker.
Architecture
New Backend Endpoint
POST /api/jobs/{job_id}/change-visibility
Auth: Requires authenticated user who is the job creator OR an admin.
Request body:
{
"target_visibility": "public" | "private"
}
Response:
{
"status": "success" | "processing" | "error",
"job_id": "...",
"message": "...",
"previous_visibility": "public" | "private",
"new_visibility": "public" | "private",
"reprocessing_required": true | false
}
Why a new endpoint instead of extending admin PATCH?
- The PATCH endpoint is admin-only; this needs to work for regular users
- The logic is complex enough to warrant its own endpoint with clear semantics
- We need to orchestrate multiple steps atomically (delete outputs, update fields, trigger workers)
- The existing PATCH toggle-to-private behavior is kept as-is for admin convenience (backwards compat)
Validation:
- Job must be in
COMPLETEstatus (notFAILED,PREP_COMPLETE, or in-progress) - Job must not be a tenant job (
tenant_idmust be null) - Target visibility must differ from current visibility
- Job must not already be undergoing a visibility change (guard against double-clicks)
Backend Implementation Details
Public -> Private (distribution-only re-run)
This flow is novel -- we don't have an existing mechanism to re-run just distribution. Options:
Option 1: Dedicated _redistribute function (recommended)
Create a lightweight function that:
- Downloads finals from GCS to a temp dir
- Creates an OrchestratorConfig with private distribution settings
- Runs only
_run_organization()+_run_distribution()+_run_notifications()stages - Updates job state_data
This avoids re-encoding entirely. We'd extract the distribution stages into a callable unit.
Option 2: Re-run full video worker with cached encoding The GCE encoding worker has a cache -- if the job was recently encoded, it returns cached results. But this is fragile (cache might be cleared) and still downloads/re-uploads files unnecessarily.
Going with Option 1.
Implementation:
- New function in
video_worker.py:async def redistribute_video(job_id: str) -> bool - Modeled after
generate_video_orchestrated()but skips encoding - Downloads existing finals from GCS
jobs/{job_id}/finals/ - Creates orchestrator with appropriate distribution config
- Runs organization + distribution stages only
Private -> Public (full re-process)
This reuses existing infrastructure more directly:
- Call modified
delete_job_outputs()that also cleans up screens and rendered video - Reset style fields on the job document
- Set status to
LYRICS_COMPLETEwithregen_restore_status = "review_complete" - Trigger screens worker via
worker_service.trigger_screens_worker(job_id) - The screens worker generates screens, then sees
regen_restore_statusand restores toREVIEW_COMPLETE REVIEW_COMPLETEtriggers render worker -> video worker ->COMPLETE
Issue: Screens worker regen_restore_status behavior
Looking at the existing regenerate-screens endpoint (admin.py:2003), it sets regen_restore_status to the original status. The screens worker checks this and restores to that status instead of going to AWAITING_REVIEW.
For our case, we want to restore to REVIEW_COMPLETE (not back to COMPLETE), so the pipeline continues through render + encode. This fits the existing mechanism perfectly -- we just set regen_restore_status = "review_complete".
Issue: Screens worker does NOT auto-trigger the render worker
Verified: The screens worker's regen_restore_status handling (screens_worker.py:197-204) just does a raw Firestore update to set the status -- it does not trigger any downstream worker. The render worker is only triggered from the complete-review API endpoint (jobs.py:992).
Solution: Modify the screens worker's regen_restore_status handling to also trigger the render worker when the restore status is review_complete. This is the cleanest approach because:
- The trigger logic stays in the worker pipeline (not in a separate polling mechanism)
- It's a small, focused change to
screens_worker.py - It reuses
worker_service.trigger_render_video_worker(job_id)
# In screens_worker.py, after restoring status:
if regen_restore_status == "review_complete":
# Visibility change flow: trigger render worker to continue pipeline
from backend.services.worker_service import get_worker_service
worker_service = get_worker_service()
await worker_service.trigger_render_video_worker(job_id)
Modified delete_job_outputs for Public -> Private
The current delete_job_outputs() always deletes GCS finals. For public->private, we need to keep them. Two approaches:
Option A: Add keep_gcs_finals parameter (recommended)
Add an optional parameter to delete_job_outputs(): keep_gcs_finals: bool = False. When True, skip the GCS finals deletion step. The endpoint still deletes YouTube/Dropbox/GDrive and recycles the brand code.
Option B: Create separate helper function Extract the YouTube/Dropbox/GDrive deletion into a helper. More code duplication.
Going with Option A -- minimal change, backwards compatible.
Frontend Implementation
Button Location
Add a "Change Visibility" button to the OutputLinks component (frontend/components/job/OutputLinks.tsx), visible when:
- Job status is
complete - Job is not a tenant job
- Job is not currently being re-processed (guard state)
The button shows the current visibility and what it would change to:
- For public jobs: "Make Private" with a Lock icon
- For private jobs: "Make Public" with a Globe icon
Confirmation Modal
Uses the existing AlertDialog component from @radix-ui/react-alert-dialog.
Public -> Private modal:
Title: Make This Track Private?
This will:
- Remove the video from YouTube
- Remove files from Google Drive
- Move Dropbox files from public to private folder
- Assign a new private brand code (NOMADNP)
The video content won't change. This usually takes about 1-2 minutes.
You can change it back to public later, but that will require
re-rendering the video (~15-30 minutes).
[Cancel] [Make Private]
Private -> Public modal:
Title: Make This Track Public?
This will:
- Remove any custom styling (backgrounds, colors) and
reset to the standard Nomad Karaoke theme
- Regenerate title and end screens
- Re-render the karaoke video with default branding
- Publish to YouTube, Google Drive, and Dropbox
This process takes approximately 15-30 minutes. You'll receive
an email when it's complete.
Any custom styling you applied will be permanently removed.
[Cancel] [Make Public]
During Re-processing (Private -> Public)
While the job is being re-processed:
- The button is disabled and shows a spinner: "Changing to Public..."
- Job status will cycle through intermediate states (
LYRICS_COMPLETE->GENERATING_SCREENS-> etc.) - The job card should show these intermediate statuses normally
- When it reaches
COMPLETEagain, the button returns to normal
For public->private, the change is fast enough (~1-2 min) that we can show a loading spinner on the button and poll for completion.
API Integration
New method in frontend/lib/api.ts:
// In the public api object (not adminApi, since regular users can use this)
async changeVisibility(jobId: string, targetVisibility: 'public' | 'private'): Promise<ChangeVisibilityResponse> {
const response = await fetch(
`${API_BASE_URL}/api/jobs/${jobId}/change-visibility`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
...getAuthHeaders()
},
body: JSON.stringify({ target_visibility: targetVisibility }),
}
);
return handleResponse(response);
}
State Machine Considerations
New state transitions needed:
COMPLETE->LYRICS_COMPLETE(for private->public re-processing)
This transition doesn't currently exist in STATE_TRANSITIONS. We need to add it. The COMPLETE -> LYRICS_COMPLETE transition is safe because:
- We've already validated the job has completed audio+lyrics processing
- We're resetting screens/render/video progress markers
- The screens worker will pick up from
LYRICS_COMPLETEas normal
Also need: COMPLETE -> GENERATING_VIDEO (for public->private redistribution, if we transition through video worker states during redistribution). Actually, for the redistribution-only path, we might want a simpler approach -- keep the job in COMPLETE status during redistribution since it's a fast operation, or use a new transient state.
Decision: For public->private (fast redistribution), we'll:
- Set a flag
state_data.visibility_change_in_progress = trueto prevent concurrent changes - Keep status as
COMPLETE(since the operation is fast and the job is still "complete") - Run redistribution in a background task
- Clear the flag when done
For private->public (full re-process), we'll:
- Set
visibility_change_in_progress = true - Transition to
LYRICS_COMPLETE(triggering the normal pipeline) - The flag gets cleared when the job reaches
COMPLETEagain
Implementation Plan
Phase 1: Backend - Change Visibility Endpoint
Files to modify:
backend/api/routes/jobs.py-- AddPOST /jobs/{job_id}/change-visibilityendpointbackend/api/routes/admin.py-- Addkeep_gcs_finalsparam todelete_job_outputs()backend/models/job.py-- AddCOMPLETE -> LYRICS_COMPLETEstate transitionbackend/models/requests.py-- Add request/response models
Files to create:
backend/services/visibility_change_service.py-- Core logic for both flows
Phase 2: Backend - Redistribution Function
Files to modify:
backend/workers/video_worker.py-- Addredistribute_video()functionbackend/workers/video_worker_orchestrator.py-- Possibly extract distribution stages
Phase 3: Frontend - Button + Modal
Files to modify:
frontend/components/job/OutputLinks.tsx-- Add Change Visibility button + modalfrontend/lib/api.ts-- AddchangeVisibility()method + response types
Phase 4: Testing
Files to create:
backend/tests/test_change_visibility.py-- Unit tests for the visibility change servicebackend/tests/test_redistribute.py-- Unit tests for the redistribution functionfrontend/e2e/production/change-visibility.spec.ts-- E2E test (if feasible)
Test cases:
- Public -> Private: outputs deleted, finals preserved, redistributed to private destination
- Private -> Public: styles reset, screens regenerated, full pipeline completes
- Validation: rejects non-complete jobs, tenant jobs, same-visibility changes, concurrent changes
- Auth: job creator can change, admin can change, other users cannot
- Edge cases: job with no YouTube URL, job with no brand code, job with outputs already deleted
Risk Assessment
| Risk | Impact | Mitigation |
|---|---|---|
| Pipeline fails mid-visibility-change (private->public) | Job stuck in intermediate state | Use existing FAILED state handling; admin can restart |
| GCS finals deleted before redistribution completes (public->private) | Need to re-encode | Use keep_gcs_finals=True to preserve them |
| Race condition: user clicks button twice | Double processing | visibility_change_in_progress guard flag |
| Screens worker doesn't auto-trigger render after regen | Pipeline stalls | Resolved: Modify screens worker to trigger render worker when regen_restore_status == "review_complete" |
| Custom style files left as orphans in GCS | Storage waste | Clean up jobs/{job_id}/style/ during private->public |
Open Questions (Resolved)
- Who can trigger? Anyone who can see the job (creator or admin). -> New user-facing endpoint.
- Skip re-encoding for public->private? Yes, keep GCS finals and redistribute only.
- How far back for private->public? From
LYRICS_COMPLETE(screens -> render -> encode -> distribute). - Tenant jobs? Excluded. Consumer gen only.
- Custom style data? Permanently cleared on private->public. Explained in modal.
- Rate limiting? None needed.