big refactor & adding video previews

Dockerfile

@@ -9,9 +9,6 @@ RUN apt-get update && apt-get install -y \
     software-properties-common \
     git \
     ffmpeg \
-    libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libdbus-1-3 \
-    libxkbcommon0 libatspi2.0-0 libx11-6 libxcomposite1 libxdamage1 libxext6 \
-    libxfixes3 libxrandr2 libgbm1 libasound2 \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
@@ -37,4 +34,4 @@ EXPOSE 8501
 
 HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health
 
-ENTRYPOINT ["streamlit", "run", "src/streamlit_app.py", "--server.port=8501", "--server.address=0.0.0.0"]
+ENTRYPOINT ["streamlit", "run", "src/app.py", "--server.port=8501", "--server.address=0.0.0.0"]

requirements.txt

@@ -1,2 +1,3 @@
 streamlit
 git+https://github.com/francozanardi/pycaps.git
+openai

src/app.py

@@ -0,0 +1,52 @@
+import streamlit as st
+import logging
+from pycaps import logger
+
+from utils import initialize_session_state, reset_all, get_queue_status
+from ui.sidebar import render_sidebar
+from ui.step1_upload import render_step1
+from ui.step2_configure import render_step2
+from ui.step3_edit import render_step3
+from ui.step4_render import render_step4
+from ui.step5_view import render_step5
+
+st.set_page_config(layout="wide", page_title="Pycaps Demo")
+logger.set_logging_level(logging.DEBUG)
+initialize_session_state()
+
+st.title("🎬 Pycaps Demo")
+st.markdown("""
+<style>
+.stElementContainer > video {
+  max-height: 50vh;
+}
+</style>
+""", unsafe_allow_html=True)
+
+render_sidebar()
+
+step_router = {
+    1: render_step1,
+    2: render_step2,
+    3: render_step3,
+    4: render_step4,
+    5: render_step5,
+}
+
+if st.session_state.error_message:
+    st.error(st.session_state.error_message)
+    st.warning("Your session has been reset due to an error. Please try again.")
+    if st.button("🏠 Start Over"):
+        reset_all()
+        st.rerun()
+else:
+    current_step = st.session_state.current_step
+    render_function = step_router.get(current_step)
+
+    if render_function:
+        st.session_state.active_jobs = get_queue_status()
+        render_function()
+    else:
+        st.error("Invalid step. Resetting application.")
+        reset_all()
+        st.rerun()

src/config.py

@@ -0,0 +1,20 @@
+import os
+import tempfile
+
+MAX_CONCURRENT_JOBS = 3
+LOCK_DIR = os.path.join(tempfile.gettempdir(), "pycaps_locks")
+os.makedirs(LOCK_DIR, exist_ok=True)
+MAX_VIDEO_SIZE = 50 * 1024 * 1024
+LOCK_TTL_SECONDS = 20 * 60
+
+TEMPLATES_INFO = [
+    {"name": "classic", "ai_features": []},
+    {"name": "word-focus", "ai_features": []},
+    {"name": "line-focus", "ai_features": []},
+    {"name": "minimalist", "ai_features": []},
+    {"name": "neo-minimal", "ai_features": ["AI Tagger"]},
+    {"name": "hype", "ai_features": ["Auto-Emoji"]},
+    {"name": "retro-gaming", "ai_features": []},
+    {"name": "vibrant", "ai_features": []},
+]
+TEMPLATE_NAMES = [t["name"] for t in TEMPLATES_INFO]

src/streamlit_app.py

@@ -1,245 +0,0 @@
-import streamlit as st
-import os
-import tempfile
-from pathlib import Path
-import shutil
-import uuid 
-import glob 
-from editor import subtitle_editor
-
-from pycaps import Document, WhisperAudioTranscriber, TemplateLoader, logger
-from pycaps.api import ApiKeyService
-import pycaps.video.render.audio_utils as audio_utils
-import logging
-
-MAX_CONCURRENT_JOBS = 2
-LOCK_DIR = os.path.join(tempfile.gettempdir(), "pycaps_locks")
-os.makedirs(LOCK_DIR, exist_ok=True)
-MAX_VIDEO_SIZE = 50 * 1024 * 1024
-logger.set_logging_level(logging.DEBUG)
-
-def acquire_lock_slot():
-    current_jobs = glob.glob(os.path.join(LOCK_DIR, "*.lock"))
-    if len(current_jobs) >= MAX_CONCURRENT_JOBS: return None
-    lock_id = str(uuid.uuid4())
-    lock_file_path = os.path.join(LOCK_DIR, f"{lock_id}.lock")
-    with open(lock_file_path, "w") as f: f.write(str(os.getpid()))
-    return lock_file_path
-
-def release_lock_slot(lock_file_path):
-    if lock_file_path and os.path.exists(lock_file_path):
-        try: os.remove(lock_file_path)
-        except OSError: pass
-
-def get_queue_status():
-    current_jobs = len(glob.glob(os.path.join(LOCK_DIR, "*.lock")))
-    return current_jobs, MAX_CONCURRENT_JOBS
-
-def setup_api_keys(key_type: str, key: str):
-    if key:
-        if key_type == "Pycaps API (Recommended)": ApiKeyService.set(key)
-        elif key_type == "OpenAI API": os.environ["PYCAPS_OPENAI_API_KEY"] = key
-
-def cleanup_api_keys():
-    if ApiKeyService.has(): ApiKeyService.remove()
-    if "PYCAPS_OPENAI_API_KEY" in os.environ: del os.environ["PYCAPS_OPENAI_API_KEY"]
-
-def display_video(video_path):
-    with st.container():
-        st.video(video_path)
-        with open(video_path, "rb") as file: video_bytes = file.read()
-        st.download_button("⬇️ Download Video", video_bytes, f"pycaps_{Path(video_path).stem}.mp4", "video/mp4")
-
-def build_pipeline_from_state():
-    if not st.session_state.video_path or not st.session_state.selected_template:
-        return None
-    
-    builder = TemplateLoader(st.session_state.selected_template).with_input_video(st.session_state.video_path).load(False)
-    pipeline = builder.build()
-    return pipeline
-
-def go_to_step(step): st.session_state.current_step = step
-def reset_all():
-    persisted_keys = ['api_key_type', 'api_key_input']
-    if 'video_path' in st.session_state and st.session_state.video_path and os.path.exists(st.session_state.video_path):
-        os.remove(st.session_state.video_path)
-    for key in list(st.session_state.keys()):
-        if key not in persisted_keys: del st.session_state[key]
-    go_to_step(1)
-
-if 'current_step' not in st.session_state: st.session_state.current_step = 1
-if 'video_path' not in st.session_state: st.session_state.video_path = None
-if 'transcribed_doc' not in st.session_state: st.session_state.transcribed_doc = None
-if 'processed_doc' not in st.session_state: st.session_state.processed_doc = None
-if 'edit_requested' not in st.session_state: st.session_state.edit_requested = False
-if 'final_video_path' not in st.session_state: st.session_state.final_video_path = None
-if 'session_id' not in st.session_state: st.session_state.session_id = str(uuid.uuid4())
-if 'selected_template' not in st.session_state: st.session_state.selected_template = None
-
-st.set_page_config(layout="wide", page_title="Pycaps Demo")
-st.title("🎬 Pycaps Demo")
-st.markdown(f"""
-<style>
-.stElementContainer > video {{
-  max-height: 60vh;
-}}
-</style>
-""", unsafe_allow_html=True)
-with st.sidebar:
-    st.header("⚙️ API Configuration")
-    api_key_type = st.radio("Select API Key Type", ("Pycaps API (Recommended)", "OpenAI API"), key="api_key_type")
-    api_key = st.text_input("Enter your API Key", type="password", key="api_key_input")
-    st.markdown("---")
-    active_jobs, max_jobs = get_queue_status()
-    st.metric(label="Jobs Running", value=f"{active_jobs} / {max_jobs}")
-
-# ==============================================================================
-# STEP 1: UPLOAD & TRANSCRIBE
-# ==============================================================================
-if st.session_state.current_step == 1:
-    st.header("Upload Your Video")
-    uploaded_file = st.file_uploader("Select a video file (max 50MB)", type=["mp4", "mov"], key=f"uploader_{st.session_state.session_id}")
-    if uploaded_file:
-        if uploaded_file.size > MAX_VIDEO_SIZE:
-            st.error(f"File is too large ({uploaded_file.size / (1024*1024):.1f}MB). Max is {MAX_VIDEO_SIZE // (1024*1024)}MB.")
-        elif st.button("Start", type="primary"):
-            with tempfile.TemporaryDirectory() as temp_dir:
-                video_path = Path(temp_dir) / uploaded_file.name
-                with open(video_path, "wb") as f: f.write(uploaded_file.getbuffer())
-                with st.spinner("Analyzing audio... 🎧"):
-                    try:
-                        audio_path = os.path.join(temp_dir, "audio.wav")
-                        audio_utils.extract_audio_for_whisper(str(video_path), audio_path)
-                        transcriber = WhisperAudioTranscriber(model_size="base")
-                        document = transcriber.transcribe(audio_path)
-
-                        st.session_state.transcribed_doc = document.to_dict()
-                        persisted_path = os.path.join(tempfile.gettempdir(), f"session_{st.session_state.session_id}.mp4")
-                        shutil.copy(video_path, persisted_path)
-                        st.session_state.video_path = persisted_path
-                        go_to_step(2)
-                        st.rerun()
-                    except Exception as e:
-                        st.error(f"Transcription failed: {e}")
-                        import traceback; traceback.print_exc()
-
-# ==============================================================================
-# STEP 2: CONFIGURE TEMPLATE AND PROCESS
-# ==============================================================================
-elif st.session_state.current_step == 2:
-    st.header("Configure & Process")
-    template_name = st.selectbox("Choose a Style", ["classic", "word-focus", "line-focus", "minimalist", "neo-minimal", "hype", "retro-gaming", "vibrant"])
-    st.session_state.edit_requested = st.checkbox("I want to review and edit the processed subtitles before rendering.", value=st.session_state.edit_requested)
-    
-    if st.button("Next", type="primary"):
-        st.session_state.selected_template = template_name
-        with st.spinner("Applying template, effects, and tags... ⚙️"):
-            try:
-                pipeline = build_pipeline_from_state()
-                if not pipeline:
-                    raise RuntimeError("Could not build pipeline. Missing video or template selection.")
-
-                setup_api_keys(api_key_type, api_key)
-                pipeline.prepare()
-                document = Document.from_dict(st.session_state.transcribed_doc)
-                processed_document = pipeline.process_document(document)
-                pipeline.close()
-                
-                st.session_state.processed_doc = processed_document.to_dict()
-                go_to_step(3)
-                st.rerun()
-
-
-            except Exception as e:
-                st.error(f"Processing failed: {e}")
-                import traceback; traceback.print_exc()
-            finally:
-                cleanup_api_keys()
-
-    if st.button("⬅️ Back"): reset_all(); st.rerun()
-
-# ==============================================================================
-# STEP 3: EDIT (OPTIONAL) & RENDER
-# ==============================================================================
-elif st.session_state.current_step == 3:
-    if st.session_state.edit_requested:
-        st.header("Edit Subtitles")
-        st.markdown("Make your changes in the editor below. Your progress is saved automatically when you click 'Save' or 'Cancel'.")
-
-        editor_result = subtitle_editor(
-            initial_document=st.session_state.processed_doc,
-            key=f"editor_{st.session_state.session_id}"
-        )
-
-        if editor_result is not None:
-            if editor_result.get("action") == "save":
-                st.session_state.processed_doc = editor_result.get("document")
-                st.toast("✅ Subtitles saved!")
-            elif editor_result.get("action") == "cancel":
-                st.toast("Editing cancelled.")
-            
-            go_to_step(4)
-            st.rerun()
-
-    else:
-        go_to_step(4)
-        st.rerun()
-
-# ==============================================================================
-# STEP 4: RENDER & VIEW
-# ==============================================================================
-elif st.session_state.current_step == 4:
-    st.header("Final Render")
-    
-    lock_file = acquire_lock_slot()
-    if not lock_file:
-        st.warning("🚧 Renderer is at full capacity. Please try again.")
-        if st.button("⬅️ Go Back to Configuration"): go_to_step(2); st.rerun()
-    else:
-        try:
-            with st.spinner("Rendering final video... This is the last step! 🎬"):
-                pipeline = build_pipeline_from_state()
-                if not pipeline:
-                    raise RuntimeError("Could not build pipeline for rendering.")
-                
-                setup_api_keys(api_key_type, api_key)
-                pipeline.prepare()
-
-                document_to_render = Document.from_dict(st.session_state.processed_doc)
-                
-                pipeline.render(document_to_render)
-                
-                if pipeline._output_video_path and os.path.exists(pipeline._output_video_path):
-                    st.session_state.final_video_path = pipeline._output_video_path
-                    go_to_step(5)
-                    st.rerun()
-                else:
-                    st.error("Render failed. Check the logs.")
-        finally:
-            release_lock_slot(lock_file)
-            if 'pipeline_instance' in st.session_state:
-                st.session_state.pipeline_instance.close()
-                del st.session_state.pipeline_instance
-            
-# ==============================================================================
-# STEP 5: VIEW & DOWNLOAD
-# ==============================================================================
-elif st.session_state.current_step == 5:
-    st.header("Your Video is Ready!")
-    if 'final_video_path' in st.session_state and st.session_state.final_video_path:
-        display_video(st.session_state.final_video_path)
-    else:
-        st.error("Could not find the final video.")
-
-    col1, col2 = st.columns(2)
-    with col1:
-        if st.button("⬅️ Choose Another Style", use_container_width=True):
-            keys_to_delete = ['processed_doc', 'final_video_path', 'edit_requested']
-            for key in keys_to_delete:
-                if key in st.session_state: del st.session_state[key]
-            go_to_step(2)
-            st.rerun()
-    with col2:
-        if st.button("🏠 Start with a New Video", use_container_width=True):
-            reset_all()
-            st.rerun()

src/ui/sidebar.py

@@ -0,0 +1,36 @@
+import streamlit as st
+from utils import get_queue_status
+from config import MAX_CONCURRENT_JOBS
+
+def render_sidebar():
+    with st.sidebar:
+        st.header("⚙️ API Configuration")
+        st.info(
+            "API keys are optional and only required for AI features "
+            "like **Auto-Emoji** or **AI Tagger**."
+        )
+        st.radio("Select API Key Type", ("OpenAI API"), key="api_key_type")
+        st.text_input("Enter your API Key", type="password", key="api_key_input")
+        
+        st.markdown("---")
+        
+        st.header("📊 Job Status")
+        active_jobs = get_queue_status()
+        st.metric(
+            label="Concurrent Jobs Running",
+            value=f"{active_jobs} / {MAX_CONCURRENT_JOBS}"
+        )
+
+        st.markdown("---")
+
+        st.header("About Pycaps")
+        st.markdown(
+            "**Pycaps** is an open-source tool for adding stylish, "
+            "animated subtitles to videos."
+        )
+        st.markdown(
+            "[⭐ Star on GitHub](https://github.com/francozanardi/pycaps)"
+        )
+        st.markdown(
+            "[📄 Read the Docs](https://github.com/francozanardi/pycaps/blob/main/README.md)"
+        )

src/ui/step1_upload.py

@@ -0,0 +1,62 @@
+import streamlit as st
+import os
+import tempfile
+import shutil
+from pathlib import Path
+import pycaps.video.render.audio_utils as audio_utils
+from pycaps import WhisperAudioTranscriber
+from utils import go_to_step, acquire_lock_slot, handle_unexpected_exception
+from config import MAX_VIDEO_SIZE, MAX_CONCURRENT_JOBS
+
+def render_step1():
+    st.header("Upload Your Video")
+    
+    if st.session_state.active_jobs >= MAX_CONCURRENT_JOBS:
+        st.warning("🚧 All our processing slots are currently busy. Please check back in a few minutes.")
+        st.info("Tip: You can also duplicate this space and get your own private and free, full-speed version instantly!")
+        st.progress(1.0)
+        if st.button("Refresh Status"):
+            st.rerun()
+        return
+
+    uploaded_file = st.file_uploader(
+        f"Select a video file (max {MAX_VIDEO_SIZE // (1024*1024)}MB)",
+        type=["mp4", "mov"],
+        key=f"uploader_{st.session_state.session_id}"
+    )
+
+    if not uploaded_file:
+        return
+
+    if uploaded_file.size > MAX_VIDEO_SIZE:
+        st.error(f"File is too large ({uploaded_file.size / (1024*1024):.1f}MB). Max is {MAX_VIDEO_SIZE // (1024*1024)}MB.")
+        return
+
+    if st.button("Start", type="primary"):
+        lock_file = acquire_lock_slot()
+        if not lock_file:
+            st.error("Sorry, all slots were taken just now. Please try again.")
+            st.rerun()
+        
+        st.session_state.lock_file_path = lock_file
+        try:
+            with tempfile.TemporaryDirectory() as temp_dir:
+                video_path = Path(temp_dir) / uploaded_file.name
+                with open(video_path, "wb") as f:
+                    f.write(uploaded_file.getbuffer())
+
+                with st.spinner("Analyzing audio... 🎧"):
+                    audio_path = os.path.join(temp_dir, "audio.wav")
+                    audio_utils.extract_audio_for_whisper(str(video_path), audio_path)
+                    transcriber = WhisperAudioTranscriber(model_size="base")
+                    document = transcriber.transcribe(audio_path)
+
+                    st.session_state.transcribed_doc = document.to_dict()
+                    persisted_path = os.path.join(tempfile.gettempdir(), f"session_{st.session_state.session_id}.mp4")
+                    shutil.copy(video_path, persisted_path)
+                    st.session_state.video_path = persisted_path
+                    
+                    go_to_step(2)
+                    st.rerun()
+        except Exception as e:
+            handle_unexpected_exception(e)

src/ui/step2_configure.py

@@ -0,0 +1,108 @@
+import streamlit as st
+import os
+from pycaps import Document, TemplateLoader
+from utils import go_to_step, reset_all, build_pipeline_from_state, setup_api_keys, cleanup_api_keys, handle_unexpected_exception
+from config import TEMPLATE_NAMES, TEMPLATES_INFO
+
+def render_step2():
+    st.header("Configure & Process")
+    api_key = st.session_state.get('api_key_input')
+    api_key_type = st.session_state.get('api_key_type')
+
+    col1, col2 = st.columns([1, 1])
+    with col1:
+        render_configuration_column(api_key, api_key_type)
+    with col2:
+        render_preview_column()
+
+def render_configuration_column(api_key, api_key_type):
+    st.subheader("Configuration")
+    template_name = st.selectbox("Choose a Style", TEMPLATE_NAMES)
+    st.session_state.selected_template = template_name
+    
+    selected_template_info = next((t for t in TEMPLATES_INFO if t["name"] == template_name), None)
+    if selected_template_info and selected_template_info["ai_features"]:
+        ai_features_str = ", ".join(selected_template_info["ai_features"])
+        if not api_key:
+            st.warning(f"⚠️ This template uses AI features ({ai_features_str}). "
+                       "Please provide an API key in the sidebar to enable them. "
+                       "Otherwise, they will be ignored during processing.")
+        else:
+            st.info(f"✨ This template uses AI features: {ai_features_str}.")
+
+    st.session_state.edit_requested = st.checkbox(
+        "I want to review and edit the processed subtitles before rendering.", 
+        value=st.session_state.get('edit_requested', False)
+    )
+    
+    st.write("")
+    b_next_col, b_back_col = st.columns(2)
+    with b_next_col:
+        if st.button("Render Video ➡️", type="primary", use_container_width=True):
+            with st.spinner("Applying template, effects, and tags... ⚙️"):
+                try:
+                    pipeline = build_pipeline_from_state()
+                    if not pipeline:
+                        raise RuntimeError("Could not build pipeline. Missing video or template selection.")
+
+                    setup_api_keys(api_key_type, api_key)
+                    # NOTE: Assuming your pipeline has methods `prepare` and `process_document`
+                    pipeline.prepare() 
+                    document = Document.from_dict(st.session_state.transcribed_doc)
+                    processed_document = pipeline.process_document(document)
+                    pipeline.close()
+                    
+                    st.session_state.processed_doc = processed_document.to_dict()
+                    go_to_step(3)
+                    st.rerun()
+                except Exception as e:
+                    handle_unexpected_exception(e)
+                finally:
+                    cleanup_api_keys()
+
+    with b_back_col:
+        if st.button("⬅️ Start Over", use_container_width=True):
+            reset_all()
+            st.rerun()
+
+def render_preview_column():
+    st.subheader("Live Preview")
+    st.markdown("Generate a short, low-quality video preview with the selected style. This takes a few seconds.")
+    st.warning("AI features (auto-emojis, ai tagger) are ignored in the preview.")
+
+    preview_container = st.container()
+    template_name = st.session_state.get('selected_template') # Use a local var for clarity
+    
+    has_preview_for_template = template_name in st.session_state.previews
+    is_button_disabled = has_preview_for_template or st.session_state.preview_generating
+
+    if st.button("Generate Preview ⚡", use_container_width=True, disabled=is_button_disabled):
+        st.session_state.preview_generating = True
+        st.rerun()
+
+    if st.session_state.preview_generating:
+        try:
+            with st.spinner("Generating preview video... ⚡"):
+                builder = TemplateLoader(template_name).with_input_video(st.session_state.video_path).load(False)
+                pipeline = builder.build(preview_time=(0, 5))
+                document = Document.from_dict(st.session_state.transcribed_doc)
+                
+                pipeline.prepare()
+                processed_document = pipeline.process_document(document)
+                pipeline.render(processed_document)
+                pipeline.close()
+
+                preview_output_path = pipeline._output_video_path
+                if preview_output_path and os.path.exists(preview_output_path):
+                    preview_container.video(preview_output_path)
+                    st.session_state.previews[template_name] = preview_output_path
+                else:
+                    preview_container.error("Could not generate preview.")
+        except Exception as e:
+            handle_unexpected_exception(e)
+        finally:
+            st.session_state.preview_generating = False
+            st.rerun()
+    
+    if has_preview_for_template:
+        preview_container.video(st.session_state.previews[template_name])

src/ui/step3_edit.py

@@ -0,0 +1,29 @@
+import streamlit as st
+from editor import subtitle_editor
+from utils import go_to_step, handle_unexpected_exception
+
+def render_step3():
+    if not st.session_state.edit_requested:
+        go_to_step(4)
+        st.rerun()
+
+    st.header("Edit Subtitles")
+    st.markdown("Make your changes in the editor below. Clicking 'Save' applies them, while 'Cancel' discards them.")
+
+    editor_result = subtitle_editor(
+        initial_document=st.session_state.processed_doc,
+        key=f"editor_{st.session_state.session_id}"
+    )
+
+    if editor_result is not None:
+        try:
+            if editor_result.get("action") == "save":
+                st.session_state.processed_doc = editor_result.get("document")
+                st.toast("✅ Subtitles saved!")
+            elif editor_result.get("action") == "cancel":
+                st.toast("Editing cancelled. Changes ignored.")
+            
+            go_to_step(4)
+            st.rerun()
+        except Exception as e:
+            handle_unexpected_exception(e)

src/ui/step4_render.py

@@ -0,0 +1,29 @@
+import streamlit as st
+import os
+from pycaps import Document
+from utils import go_to_step, build_pipeline_from_state, setup_api_keys, handle_unexpected_exception
+
+def render_step4():
+    st.header("Final Render")
+    api_key = st.session_state.get('api_key_input')
+    api_key_type = st.session_state.get('api_key_type')
+    
+    try:
+        with st.spinner("Rendering final video... This is the last step! 🎬"):
+            pipeline = build_pipeline_from_state()
+            if not pipeline:
+                raise RuntimeError("Could not build pipeline for rendering.")
+            
+            setup_api_keys(api_key_type, api_key)
+            pipeline.prepare()
+            document_to_render = Document.from_dict(st.session_state.processed_doc)
+            pipeline.render(document_to_render)
+            
+            if pipeline._output_video_path and os.path.exists(pipeline._output_video_path):
+                st.session_state.final_video_path = pipeline._output_video_path
+                go_to_step(5)
+                st.rerun()
+            else:
+                st.error("Render failed. Check the logs.")
+    except Exception as e:
+        handle_unexpected_exception(e)

src/ui/step5_view.py

@@ -0,0 +1,34 @@
+import streamlit as st
+from utils import go_to_step, reset_all, release_lock_slot, acquire_lock_slot, display_video
+
+def render_step5():
+    st.header("Your Video is Ready!")
+
+    if st.session_state.lock_file_path:
+        release_lock_slot(st.session_state.lock_file_path)
+        st.session_state.lock_file_path = None
+
+    if 'final_video_path' in st.session_state and st.session_state.final_video_path:
+        display_video(st.session_state.final_video_path)
+    else:
+        st.error("Could not find the final video.")
+
+    col1, col2 = st.columns(2)
+    with col1:
+        if st.button("⬅️ Choose Another Style", use_container_width=True):
+            lock_file = acquire_lock_slot()
+            if not lock_file:
+                st.warning("🚧 All our processing slots are currently busy. Please check back in a few minutes.")
+            else:
+                st.session_state.lock_file_path = lock_file
+                keys_to_delete = ['processed_doc', 'final_video_path', 'edit_requested']
+                for key in keys_to_delete:
+                    if key in st.session_state:
+                        del st.session_state[key]
+                go_to_step(2)
+                st.rerun()
+
+    with col2:
+        if st.button("🏠 Start with a New Video", use_container_width=True):
+            reset_all()
+            st.rerun()

src/utils.py

@@ -0,0 +1,125 @@
+import streamlit as st
+import os
+import time
+import glob
+import uuid
+from pathlib import Path
+
+from pycaps.api import ApiKeyService
+from pycaps import TemplateLoader
+from config import LOCK_DIR, LOCK_TTL_SECONDS, MAX_CONCURRENT_JOBS
+
+# --- Lock Management ---
+
+def release_lock_slot(lock_file_path):
+    if lock_file_path and os.path.exists(lock_file_path):
+        try:
+            os.remove(lock_file_path)
+        except OSError:
+            pass
+
+def cleanup_stale_locks():
+    for lock_file in glob.glob(os.path.join(LOCK_DIR, "*.lock")):
+        try:
+            timestamp_str = Path(lock_file).stem.split('_')[0]
+            creation_time = float(timestamp_str)
+            if time.time() - creation_time > LOCK_TTL_SECONDS:
+                release_lock_slot(lock_file)
+        except (ValueError, IndexError):
+            release_lock_slot(lock_file)
+
+def acquire_lock_slot():
+    cleanup_stale_locks()
+    current_jobs = len(glob.glob(os.path.join(LOCK_DIR, "*.lock")))
+    if current_jobs >= MAX_CONCURRENT_JOBS:
+        return None
+    
+    lock_id = f"{time.time()}_{uuid.uuid4()}"
+    lock_file_path = os.path.join(LOCK_DIR, f"{lock_id}.lock")
+    with open(lock_file_path, "w") as f:
+        f.write(str(os.getpid()))
+    return lock_file_path
+
+def get_queue_status():
+    cleanup_stale_locks()
+    current_jobs = len(glob.glob(os.path.join(LOCK_DIR, "*.lock")))
+    return current_jobs
+
+# --- API Key Management ---
+
+def setup_api_keys(key_type: str, key: str):
+    if key:
+        if key_type == "Pycaps API (Recommended)":
+            ApiKeyService.set(key)
+        elif key_type == "OpenAI API":
+            os.environ["PYCAPS_OPENAI_API_KEY"] = key
+
+def cleanup_api_keys():
+    if ApiKeyService.has():
+        ApiKeyService.remove()
+    if "PYCAPS_OPENAI_API_KEY" in os.environ:
+        del os.environ["PYCAPS_OPENAI_API_KEY"]
+
+# --- State Management ---
+
+def go_to_step(step):
+    st.session_state.current_step = step
+
+def reset_all():
+    if 'lock_file_path' in st.session_state and st.session_state.lock_file_path:
+        release_lock_slot(st.session_state.lock_file_path)
+
+    persisted_keys = ['api_key_type', 'api_key_input']
+    if 'video_path' in st.session_state and st.session_state.video_path and os.path.exists(st.session_state.video_path):
+        os.remove(st.session_state.video_path)
+        
+    for key in list(st.session_state.keys()):
+        if key not in persisted_keys:
+            del st.session_state[key]
+            
+    go_to_step(1)
+
+def initialize_session_state():
+    defaults = {
+        'current_step': 1,
+        'video_path': None,
+        'transcribed_doc': None,
+        'processed_doc': None,
+        'edit_requested': False,
+        'final_video_path': None,
+        'session_id': str(uuid.uuid4()),
+        'selected_template': None,
+        'previews': {},
+        'preview_generating': False,
+        'lock_file_path': None,
+        'error_message': None,
+    }
+    for key, value in defaults.items():
+        if key not in st.session_state:
+            st.session_state[key] = value
+
+# --- Pipeline & Display ---
+
+def build_pipeline_from_state():
+    if not st.session_state.video_path or not st.session_state.selected_template:
+        return None
+    return TemplateLoader(st.session_state.selected_template).with_input_video(st.session_state.video_path).load()
+
+def handle_unexpected_exception(e):
+    st.session_state.error_message = f"Unexpected error: {e}"
+    if st.session_state.lock_file_path:
+        release_lock_slot(st.session_state.lock_file_path)
+    st.session_state.lock_file_path = None
+    import traceback
+    traceback.print_exc()
+    st.rerun()
+
+def display_video(video_path):
+    with st.container():
+        st.video(video_path)
+        with open(video_path, "rb") as file:
+            video_bytes = file.read()
+        st.download_button(
+            "⬇️ Download Video", video_bytes, 
+            f"pycaps_{Path(video_path).stem}.mp4", "video/mp4"
+        )