Add knowledge-issue news style

.github/workflows/deploy_to_hf.yml

@@ -0,0 +1,22 @@
+name: Deploy to Hugging Face Space
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Push to Hugging Face Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          git remote add space https://PLXR:${HF_TOKEN}@huggingface.co/spaces/PLXR/youtube_auto_image1
+          git push --force space main

app.py

@@ -2,6 +2,8 @@ import streamlit as st
 import os
 import io
 import concurrent.futures
+import datetime
+import zipfile
 from PIL import Image
 from google import genai
 
@@ -9,6 +11,7 @@ from google import genai
 import logic_image
 import logic_seo
 import logic_tts
+import utils
 from config_style import STYLE_DEFINITIONS, THUMBNAIL_STRATEGIES
 
 # ==========================================
@@ -28,6 +31,10 @@ if 'final_audio' not in st.session_state:
     st.session_state['final_audio'] = None
 if 'shared_script' not in st.session_state:
     st.session_state['shared_script'] = ""
+if 'thumbnail_results' not in st.session_state:
+    st.session_state['thumbnail_results'] = []
+if 'thumbnail_text' not in st.session_state:
+    st.session_state['thumbnail_text'] = ""
 
 # [CSS] 다크모드 + 오렌지 포인트 디자인
 st.markdown("""
@@ -121,15 +128,10 @@ with st.sidebar:
     st.divider()
 
     st.markdown("### 🎨 Model Engine")
-    model_choice = st.radio("사용할 모델", ["⚡ Fast (Gemini 2.0)", "🚀 Pro (Imagen 3)"], label_visibility="collapsed")
-    
-    if "Fast" in model_choice:
-        image_model_id = "gemini-2.0-flash" 
-        text_model_id = "gemini-2.0-flash"
-    else:
-        # [복구] 사용자님이 원하시던 그 모델 ID!
-        image_model_id = "gemini-3-pro-image-preview" 
-        text_model_id = "gemini-3-pro-preview" 
+    st.radio("사용할 모델", ["🚀 Pro (Imagen 3)"], label_visibility="collapsed")
+    # [고정] Pro 모델만 사용
+    image_model_id = "gemini-3-pro-image-preview"
+    text_model_id = "gemini-3-pro-preview"
 
     st.divider()
 
@@ -147,7 +149,7 @@ with st.sidebar:
     st.markdown("<br>", unsafe_allow_html=True)
     
     st.caption("Image Scene Split (이미지 생성용)")
-    duration_per_scene = st.slider("장면당 시간(초)", 3, 30, 5)
+    duration_per_scene = st.slider("장면당 시간(초)", 5, 600, 5, step=5)
     split_criteria = duration_per_scene * 8
     st.info(f"💡 {duration_per_scene}초 (약 {split_criteria}자) 단위로 장면을 나눕니다.")
     st.caption("※ TTS는 설정과 무관하게 500자 단위로 최적화됩니다.")
@@ -228,24 +230,48 @@ with tab1:
             
             st.toast(f"📜 {len(scenes_text)}개 장면으로 분할하여 생성을 시작합니다.")
             
-            client = genai.Client(api_key=api_key)
             progress_text = "AI 화가가 그림을 그리는 중입니다..."
             my_bar = st.progress(0, text=progress_text)
-            
+
             temp_results = [None] * len(scenes_text)
+
+            def run_scene_task(task_index, task_text):
+                client = genai.Client(api_key=api_key)
+                return logic_image.process_scene_task(
+                    task_index,
+                    {'text': task_text},
+                    selected_style,
+                    custom_style_input,
+                    client,
+                    text_model_id,
+                    image_model_id,
+                    aspect_ratio,
+                    reference_image
+                )
             
             # 안정성 위해 max_workers=2
             with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor:
                 future_to_idx = {
-                    executor.submit(logic_image.process_scene_task, i, {'text': text}, selected_style, custom_style_input, client, text_model_id, image_model_id, aspect_ratio, reference_image): i 
+                    executor.submit(run_scene_task, i, text): i
                     for i, text in enumerate(scenes_text)
                 }
                 completed = 0
                 for future in concurrent.futures.as_completed(future_to_idx):
-                    idx, prompt, img = future.result()
-                    temp_results[idx] = (prompt, img, scenes_text[idx])
-                    completed += 1
-                    my_bar.progress(completed / len(scenes_text), text=f"Scene {idx+1} 완료!")
+                    idx = future_to_idx[future]
+                    try:
+                        _, prompt, img = future.result()
+                        temp_results[idx] = {
+                            "prompt": prompt,
+                            "img_bytes": img,
+                            "script_text": scenes_text[idx],
+                        }
+                        completed += 1
+                        my_bar.progress(completed / len(scenes_text), text=f"Scene {idx+1} 완료!")
+                    except Exception as exc:
+                        completed += 1
+                        my_bar.progress(completed / len(scenes_text), text=f"Scene {idx+1} 실패")
+                        st.error(f"Scene {idx+1} 생성에 실패했습니다.")
+                        st.exception(exc)
             
             st.session_state['scene_results'] = temp_results
             my_bar.empty()
@@ -256,9 +282,46 @@ with tab1:
         st.divider()
         st.subheader("🎬 Scene Results")
         
+        def _normalize_scene_item(item):
+            if isinstance(item, dict):
+                return item
+            if isinstance(item, (list, tuple)) and len(item) == 3:
+                prompt_text, img_bytes, script_text = item
+                return {
+                    "prompt": prompt_text,
+                    "img_bytes": img_bytes,
+                    "script_text": script_text,
+                }
+            return {}
+
+        scene_zip_buffer = io.BytesIO()
+        with zipfile.ZipFile(scene_zip_buffer, "w") as zip_file:
+            for i, item in enumerate(st.session_state['scene_results']):
+                item = _normalize_scene_item(item)
+                if not item:
+                    continue
+                img_data = item.get("img_bytes")
+                if img_data:
+                    snippet = utils.make_scene_snippet(item.get("script_text", ""))
+                    zip_file.writestr(f"scene_{i+1:02d}_{snippet}.png", img_data)
+        scene_zip_buffer.seek(0)
+        if scene_zip_buffer.getbuffer().nbytes > 0:
+            timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M")
+            st.download_button(
+                label="⬇️ 모든 이미지 한번에 다운로드",
+                data=scene_zip_buffer.getvalue(),
+                file_name=f"scenes_{timestamp}.zip",
+                mime="application/zip",
+                use_container_width=True
+            )
+
         for i, item in enumerate(st.session_state['scene_results']):
-            if item is None: continue
-            p_text, img_data, s_text = item
+            item = _normalize_scene_item(item)
+            if not item:
+                continue
+            p_text = item.get("prompt", "")
+            img_data = item.get("img_bytes")
+            s_text = item.get("script_text", "")
             
             with st.container():
                 c1, c2 = st.columns([1, 2])
@@ -267,15 +330,18 @@ with tab1:
                         try:
                             image = Image.open(io.BytesIO(img_data))
                             st.image(image, use_container_width=True)
+                            snippet = utils.make_scene_snippet(s_text)
                             st.download_button(
                                 label="⬇️ 다운로드",
                                 data=img_data,
-                                file_name=f"scene_{i+1}.png",
+                                file_name=f"scene_{i+1:02d}_{snippet}.png",
                                 mime="image/png",
                                 key=f"dl_btn_{i}",
                                 use_container_width=True
                             )
-                        except: st.error("이미지 오류")
+                        except Exception as exc:
+                            st.error("이미지 처리 중 오류가 발생했습니다.")
+                            st.exception(exc)
                     else: st.warning("이미지 없음")
                 with c2:
                     st.markdown(f"**Scene {i+1}**")
@@ -285,9 +351,29 @@ with tab1:
                         else:
                             client = genai.Client(api_key=api_key)
                             with st.spinner("다시 그리는 중..."):
-                                _, new_p, new_img = logic_image.process_scene_task(i, {'text': s_text}, selected_style, custom_style_input, client, text_model_id, image_model_id, aspect_ratio, reference_image)
-                                st.session_state['scene_results'][i] = (new_p, new_img, s_text)
-                                st.rerun()
+                                try:
+                                    _, new_p, new_img = logic_image.process_scene_task(
+                                        i,
+                                        {'text': s_text},
+                                        selected_style,
+                                        custom_style_input,
+                                        client,
+                                        text_model_id,
+                                        image_model_id,
+                                        aspect_ratio,
+                                        reference_image
+                                    )
+                                    st.session_state['scene_results'][i] = {
+                                        "prompt": new_p,
+                                        "img_bytes": new_img,
+                                        "script_text": s_text,
+                                    }
+                                    st.rerun()
+                                except Exception as exc:
+                                    st.error("이미지 재생성에 실패했습니다.")
+                                    st.exception(exc)
+                    with st.expander("프롬프트 보기"):
+                        st.write(p_text)
                 st.divider()
 
 # ----------------------------------------------------------------
@@ -310,6 +396,8 @@ with tab2:
                 seo_result = logic_seo.generate_seo_content(client, text_model_id, seo_script)
 
                 st.session_state["seo_result"] = seo_result
+                st.session_state["thumbnail_results"] = []
+                st.session_state["thumbnail_text"] = seo_result["titles"][0] if seo_result.get("titles") else ""
                 st.success("분석 완료!")
                 
                 c_seo1, c_seo2 = st.columns(2)
@@ -323,105 +411,132 @@ with tab2:
                 st.markdown("##### 📝 설명란 (Description)")
                 st.text_area("설명란 결과", seo_result['description'], height=200)
                 st.divider()
-st.subheader("🖼️ 썸네일 생성")
 
-seo_cached = st.session_state.get("seo_result")
+    st.subheader("🖼️ 썸네일 생성")
 
-if not seo_cached:
-    st.info("SEO 분석을 먼저 실행하면 썸네일 생성 버튼이 나타납니다.")
-else:
-    strat_keys = list(THUMBNAIL_STRATEGIES.keys())
-    sel_strat = st.selectbox("썸네일 전략 선택", strat_keys, index=0)
+    seo_cached = st.session_state.get("seo_result")
 
-    # 썸네일 텍스트(메인 타이틀) 후보: SEO 추천 제목 1개를 기본값으로
-    default_thumb_text = seo_cached["titles"][0] if seo_cached.get("titles") else ""
-    thumb_text = st.text_input("썸네일 메인 문구(원하면 수정)", value=default_thumb_text)
-
-    if st.button("🧠 썸네일 프롬프트 생성", key="thumb_prompt_btn"):
-        if not api_key:
-            st.error("API Key 필요")
-        else:
-            client = genai.Client(api_key=api_key)
-
-            strategy_block = THUMBNAIL_STRATEGIES[sel_strat]
-
-            prompt = f"""
-너는 유튜브 썸네일 기획자다.
-아래 '대본'과 '전략'을 참고해서, 이미지 생성 모델에 넣을 '썸네일 프롬프트'를 만든다.
-
-[대본]
-{seo_script[:8000]}
-
-[전략]
-{strategy_block}
-
-[추가 조건]
-- 썸네일 이미지 안에 텍스트를 직접 그려 넣지 마라(글자 생성 금지).
-- 대신 '텍스트를 넣을 자리'를 구도로 확보해라(상단/하단 여백, 안전영역).
-- 국가/국기/대통령/청와대/국회의사당 등 특정 국가 상징이 자동으로 나오지 않게,
-  정치 상징물은 추상적 은유(실루엣, 조명, 군중, 무대)로 처리해라.
-- 화면비는 {aspect_ratio}.
-- 출력은 "프롬프트 텍스트 1개"만. JSON/마크다운 금지.
-
-[사용자가 넣을 메인 문구(참고만)]
-{thumb_text}
-""".strip()
-
-            res = client.models.generate_content(model=text_model_id, contents=prompt)
-            thumb_prompt = (getattr(res, "text", "") or "").strip()
-            st.session_state["thumb_prompt"] = thumb_prompt
-            st.success("썸네일 프롬프트 생성 완료!")
-            st.text_area("생성된 썸네일 프롬프트", value=thumb_prompt, height=180)
-
-    # 프롬프트가 있을 때만 이미지 생성 버튼 노출
-    thumb_prompt_cached = st.session_state.get("thumb_prompt", "")
-    if thumb_prompt_cached:
-        if st.button("🎨 썸네일 이미지 1장 생성", key="thumb_img_btn", type="primary"):
+    if not seo_cached:
+        st.info("SEO 분석을 먼저 실행하면 썸네일 생성 버튼이 나타납니다.")
+    else:
+        default_thumb_text = seo_cached["titles"][0] if seo_cached.get("titles") else ""
+        if not st.session_state["thumbnail_text"]:
+            st.session_state["thumbnail_text"] = default_thumb_text
+        thumb_text = st.text_input(
+            "썸네일 메인 문구(참고용)",
+            value=st.session_state["thumbnail_text"]
+        )
+        st.session_state["thumbnail_text"] = thumb_text
+        thumbnail_aspect_ratio = "16:9"
+
+        if st.button("🎨 썸네일 3종 동시 생성", key="thumb_img_btn", type="primary"):
             if not api_key:
                 st.error("API Key 필요")
+            elif not seo_script:
+                st.warning("대본 필요")
             else:
-                client = genai.Client(api_key=api_key)
+                progress_text = "썸네일 3종 생성 중..."
+                my_bar = st.progress(0, text=progress_text)
+
+                strategy_items = list(THUMBNAIL_STRATEGIES.items())
+                temp_results = [None] * len(strategy_items)
+
+                def run_thumbnail_task(task_index, strategy_key, strategy_text):
+                    client = genai.Client(api_key=api_key)
+                    return logic_image.process_thumbnail_task(
+                        task_index,
+                        strategy_key,
+                        strategy_text,
+                        seo_script,
+                        thumb_text,
+                        client,
+                        text_model_id,
+                        image_model_id,
+                        thumbnail_aspect_ratio
+                    )
 
-                # 이미지 생성 (generate_images 우선, 없으면 generate_content fallback)
-                img_bytes = None
-                try:
-                    if hasattr(client.models, "generate_images"):
-                        img_res = client.models.generate_images(
-                            model=image_model_id,
-                            prompt=thumb_prompt_cached
-                        )
-                        # logic_image에 있는 안전 추출 함수가 없다면 간단히 parts에서 뽑기
+                with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
+                    future_to_idx = {
+                        executor.submit(
+                            run_thumbnail_task,
+                            i,
+                            key,
+                            strategy_text
+                        ): i
+                        for i, (key, strategy_text) in enumerate(strategy_items)
+                    }
+                    completed = 0
+                    for future in concurrent.futures.as_completed(future_to_idx):
+                        idx = future_to_idx[future]
+                        strategy_key = strategy_items[idx][0]
                         try:
-                            cand = img_res.candidates[0]
-                            part = cand.content.parts[0]
-                            img_bytes = part.inline_data.data if part.inline_data else None
-                        except:
-                            img_bytes = None
-                    else:
-                        img_res = client.models.generate_content(
-                            model=image_model_id,
-                            contents=thumb_prompt_cached
-                        )
+                            _, prompt, img = future.result()
+                            temp_results[idx] = (strategy_key, prompt, img)
+                            completed += 1
+                            my_bar.progress(completed / len(strategy_items), text=f"{strategy_key} 완료!")
+                        except Exception as exc:
+                            completed += 1
+                            my_bar.progress(completed / len(strategy_items), text=f"{strategy_key} 실패")
+                            st.error(f"{strategy_key} 썸네일 생성에 실패했습니다.")
+                            st.exception(exc)
+
+                st.session_state['thumbnail_results'] = temp_results
+                my_bar.empty()
+                st.rerun()
+
+        if st.session_state.get('thumbnail_results'):
+            cols = st.columns(3)
+            for idx, (col, item) in enumerate(zip(cols, st.session_state['thumbnail_results'])):
+                if item is None:
+                    continue
+                strategy_key, prompt_text, img_data = item
+                with col:
+                    st.markdown(f"**{strategy_key}**")
+                    if img_data:
                         try:
-                            cand = img_res.candidates[0]
-                            part = cand.content.parts[0]
-                            img_bytes = part.inline_data.data if part.inline_data else None
-                        except:
-                            img_bytes = None
-                except Exception as e:
-                    st.error(f"이미지 생성 실패: {e}")
-
-                if img_bytes:
-                    st.image(Image.open(io.BytesIO(img_bytes)), use_container_width=True)
-                    st.download_button(
-                        "⬇️ 썸네일 다운로드",
-                        data=img_bytes,
-                        file_name="thumbnail.png",
-                        mime="image/png",
-                        use_container_width=True
-                    )
-                else:
-                    st.error("이미지 바이트를 추출하지 못했습니다. (모델 응답 구조 확인 필요)")
+                            image = Image.open(io.BytesIO(img_data))
+                            st.image(image, use_container_width=True)
+                            st.download_button(
+                                label="⬇️ 다운로드",
+                                data=img_data,
+                                file_name=f"thumbnail_{strategy_key.split('.')[0].lower()}.png",
+                                mime="image/png",
+                                key=f"thumb_dl_{strategy_key}",
+                                use_container_width=True
+                            )
+                        except Exception as exc:
+                            st.error("이미지 처리 중 오류가 발생했습니다.")
+                            st.exception(exc)
+                    else:
+                        st.warning("이미지 없음")
+                    if st.button("🔄 재생성", key=f"thumb_regen_{strategy_key}"):
+                        if not api_key:
+                            st.error("API Key 필요")
+                        elif not seo_script:
+                            st.warning("대본 필요")
+                        else:
+                            client = genai.Client(api_key=api_key)
+                            strategy_text = THUMBNAIL_STRATEGIES[strategy_key]
+                            with st.spinner("썸네일 재생성 중..."):
+                                try:
+                                    _, new_prompt, new_img = logic_image.process_thumbnail_task(
+                                        idx,
+                                        strategy_key,
+                                        strategy_text,
+                                        seo_script,
+                                        thumb_text,
+                                        client,
+                                        text_model_id,
+                                        image_model_id,
+                                        thumbnail_aspect_ratio
+                                    )
+                                    st.session_state['thumbnail_results'][idx] = (strategy_key, new_prompt, new_img)
+                                    st.rerun()
+                                except Exception as exc:
+                                    st.error("썸네일 재생성에 실패했습니다.")
+                                    st.exception(exc)
+                    with st.expander("프롬프트 보기"):
+                        st.write(prompt_text)
 
 # ----------------------------------------------------------------
 # [TAB 3] AI 성우 (TTS)
@@ -459,15 +574,17 @@ with tab3:
         if not api_key: st.error("API Key 필요")
         elif not tts_script: st.warning("대본 필요")
         else:
-            client = genai.Client(api_key=api_key)
-            
             # [핵심] TTS는 슬라이더 값(split_criteria)을 무시하고, 무조건 500자 단위로 고정
             chunks = logic_tts.split_text_smartly(tts_script, limit=500)
             
             audio_res = [None] * len(chunks)
             with st.status("녹음 진행 중...", expanded=True):
                 with concurrent.futures.ThreadPoolExecutor() as executor:
-                    f_map = {executor.submit(logic_tts.process_tts_task, i, c, client, tts_model_id, voice_opt): i for i, c in enumerate(chunks)}
+                    def run_tts_task(task_index, chunk):
+                        client = genai.Client(api_key=api_key)
+                        return logic_tts.process_tts_task(task_index, chunk, client, tts_model_id, voice_opt)
+
+                    f_map = {executor.submit(run_tts_task, i, c): i for i, c in enumerate(chunks)}
                     for f in concurrent.futures.as_completed(f_map):
                         idx, dat = f.result()
                         if isinstance(dat, bytes): 
@@ -478,4 +595,4 @@ with tab3:
             if final_wav:
                 st.success("오디오 생성 완료!")
                 st.audio(final_wav, format="audio/wav")
-                st.download_button("다운로드 (WAV)", final_wav, "full_audio.wav", "audio/wav")
+                st.download_button("다운로드 (WAV)", final_wav, "full_audio.wav", "audio/wav")

config_style.py

@@ -16,55 +16,51 @@ STYLE_DEFINITIONS = {
     "과학/엔지니어링": "3D Technical Animation (Fern, AiTelly Style). 화풍: Blender Cycles / Clean Rendering, 밝은 스튜디오 조명(Clean Studio Lighting). 연출: 기계/건축물의 단면도(Cutaway) 및 작동 원리 시각화. 인물: 엔지니어/과학자/교사/회사원/군인 등등 다양한 3d 캐릭터가 등장하여 기계를 조작하거나 설명하는 기능적 역할 수행. 분위기: 깔끔하고, 교육적이며, 명확함(Clear & Educational). 과도한 그림자 배제. 대본의 상황을 잘 나타내게 분활화면으로 말고 하나의 장면으로 연출.",
     
     "심플 그림판/졸라맨": "굵은 선, 단순함의 미학. 한 장면에 하나의 주제만.",
+
+    "과장된 얼굴/미니멀 바디": "극도로 과장된 2D 코믹 카툰 스타일 (Exaggerated 2D Cartoon). **캐릭터:** 몸통과 팔다리는 굵기 없는 완전한 '단순 검은 선(Simple Black Line Stick figure)'으로 처리. 옷이나 근육 묘사 생략. 반면, **얼굴**에 모든 작화력을 집중하여 이목구비, 주름, 표정, 땀방울 등을 부담스러울 정도로 리얼하고 과장되게 묘사 (Hyper-expressive Face). **장비:** 상황에 필요한 도구(총, 스마트폰, 서류 등)는 손에 쥐어주며 디테일하게 표현. **구도:** 캐릭터는 화면의 약 1/6 크기로 작게 배치(Wide Shot). 나머지 여백은 배경과 상황 묘사에 할애하여 대본의 상황을 한눈에 보여줌. **배경:** 캐릭터와 어울리는 2D 일러스트 배경. 분할 화면 금지, 하나의 장면으로 연출.",
     
     "실사 + 코믹 페이스": "Hyper-Realistic Environment with Comic Elements. 배경과 사물, 사람/동물의 몸체: '언리얼 엔진 5' 수준의 8K 실사(Photorealistic). 털, 피부 질감, 조명 완벽 구현. 사람 얼굴: 몸은 실사지만 얼굴만 '릭 앤 모티(Rick and Morty) 애니메이션 스타일'의 2D 카툰으로 합성. (참조: 큰 흰색 눈, 검은 점 눈동자, 굵은 눈썹, 단순한 입). - **표정:** 당황, 공포, 혼란, 술에 취한 듯한 '병맛' 표정 강조. 동물 눈: 털과 몸은 다큐멘터리급 실사지만, 눈만 '흰색 흰자와 검은 점 눈동자'로 된 2D 만화 눈으로 연출. 분위기: 고퀄리티 다큐멘터리인 척하는 병맛 코미디. 진지한 상황일수록 표정을 더 단순하고 멍청하게(Derp) 연출. 절대 이미지에 글씨 연출 전혀 하지 않는다.",
     
     "한국 웹툰 스타일": "한국 인기 웹툰 스타일의 고퀄리티 2D 일러스트레이션 (Korean Webtoon Style). 선명한 펜선과 화려한 채색. 집중선(Speed lines)은 정말 중요한 순간에만 가끔 사용. 캐릭터는 8등신 웹툰 주인공 스타일. 캐릭터 주변의 '상황'과 '배경(장소)'을 아주 구체적이고 밀도 있게 묘사. 단순 인물 컷보다는 주변 사물과 배경이 함께 보이는 구도 선호. 전체적으로 배경 디테일이 살아있는 네이버 웹툰 썸네일 스타일. (16:9)",
+
+    "조선 웹툰 스타일": "조선시대 배경의 한국 인기 시대극(사극) 웹툰 스타일 고퀄리티 2D 일러스트레이션 (Korean Historical Webtoon Style). 선명한 펜선과 화려한 채색. 집중선은 중요한 순간에만 사용. 캐릭터는 8등신 웹툰 주인공 스타일이며 한복을 착용. 캐릭터 주변 상황과 배경을 아주 구체적이고 밀도 있게 묘사하되, 배경은 반드시 조선시대 건축물(기와집, 초가집, 흙길)과 자연 풍경으로 한정. 현대적인 건물이나 물건은 절대 배제. 전체적으로 배경 디테일이 살아있는 네이버 시대극 웹툰 썸네일 스타일. (16:9)",
+
+    "지식이슈 뉴스": "지식/이슈/뉴스 유튜브 채널 스타일 (High-End Explainer & Documentary). [핵심]: \"뉴스 화면(자막바, 로고)\" 절대 금지. 세련된 '다큐멘터리 자료 화면' 스타일. [상황별 자동 연출 선택]: 1. 데이터/통계 -> '3D 입체 그래프' + '상승/하락 화살표' + '숫자'. 2. 인물/발언 -> '인물 사진' + '말풍선/인용구'. 3. 사물/장소 -> '고화질 실사 꼴라주(Collage)'. 4. 개념/정리 -> '흰색 구겨진 종이 배경(Top-down)' + '실사 사진 사물, 장소, 인화물(그림자 효과)' + '세련된 네이비 정보 상자 UI'. 5. 구조/시각화 -> '3D 아이콘 순서도(Flow)' 또는 'VS 대결구도(Split)'. 모드1 부터 모드5 중에서 어울리는 모드를 골고루 선택한다. 분활화면으로 연출하지 말고 하나의 화면으로 연출한다. 텍스트(텍스트상자)는 화면 아래의 자막을 넣을 공간을 방해하지 않도록 절대 하단에 연출하지 않는다.",
     
     "지브리 대작 감성": "일본 대작 귀여운 지브리풍 애니메이션 스타일 (High-Budget Anime Style). 서정적인 느낌보다는 '정보량이 많고 치밀한' 고밀도 배경 작화 (High Detail Backgrounds). 지브리 캐릭터의 표정과 행동을 '순간 포착'하듯 역동적으로 묘���. 대본의 지문을 하나도 놓치지 않고 시각화하는 '철저한 디테일' 위주. (16:9) 전체 대본에 어울리는 하나의 장면으로 연출."
 }
 
 
-# 2. 썸네일 생성 전략 정의 (추후 썸네일 생성 기능 확장 시 사용)
+# 2. 썸네일 생성 전략 정의 (A/B/C 고정)
 THUMBNAIL_STRATEGIES = {
     "A. 극적 대비 (Split Screen)": """
-    [Strategy Goal]
-    Create a thumbnail with a 50:50 vertical split.
-    Left Side: Negative/Past/Weak (Dark tone).
-    Right Side: Positive/Future/Strong (Bright tone).
-    
-    [CRITICAL RULES]
-    1. **Text Language:** THE TEXT OVERLAY MUST BE IN KOREAN. Extract key phrases from the script in KOREAN. Do not translate them.
-    2. **Composition:** Split screen vertically. Distinct visual separation.
-    3. **Style:** Realistic, high-definition, YouTube documentary style, dramatic lighting.
-    
-    [Prompt Structure to Generate]
-    "Split screen. Left: [Description of A], dark lighting, text: '[한국어 텍스트]'. Right: [Description of B], bright lighting, text: '[한국어 텍스트]'. Bottom: Big bold text '[한국어 메인 타이틀]'. Realistic style, 8k."
+    - 화면을 정확히 50:50 수직 분할.
+    - Left: 부정적/과거/약자 분위기 (어둡고 혼란).
+    - Right: 긍정적/미래/강자 분위기 (밝고 질서).
+    - 텍스트 오버레이 필수:
+      * 좌측 상단: 짧은 부정 문구
+      * 우측 상단: 짧은 긍정 문구
+      * 하단 중앙: 메인 타이틀(thumb_text)
+    - Style: Realistic documentary, dramatic lighting.
     """,
 
-    "B. 하이브리드 (Real + 2D)": """
-    [Strategy Goal]
-    Composite image. Realistic photo background + 2D vector stickman foreground.
-    
-    [CRITICAL RULES]
-    1. **Text Language:** THE TEXT OVERLAY MUST BE IN KOREAN.
-    2. **Background:** Realistic photo of key subject/location. Documentary news style.
-    3. **Foreground:** Simple 2D stickman character reacting/pointing.
-    
-    [Prompt Structure to Generate]
-    "Composite image. Background: Realistic photo of [Key Subject], news style. Foreground: 2D stickman [Action/Reaction]. Text at bottom: '[한국어 메인 타이틀]', bold font, yellow/red color."
+    "B. 실사 + 2D 스틱맨 하이브리드": """
+    - Background: 현실 다큐 뉴스 사진 스타일.
+    - Foreground: 2D 스틱맨 캐릭터가 충격/강조 리액션.
+    - 텍스트 오버레이 필수:
+      * 상단: 속보/긴급/단독 같은 서브 문구
+      * 하단: 메인 타이틀(thumb_text)
+    - Style: News composite, high CTR.
     """,
 
-    "C. 나노바나나 (2D Stickman)": """
-    [Strategy Goal]
-    Flat 2D vector art, simple stickman character.
-    
-    [CRITICAL RULES]
-    1. **Text Language:** THE TEXT OVERLAY MUST BE IN KOREAN.
-    2. **Style:** Flat 2D vector art, clean lines. NO speech bubbles.
-    3. **Logic:** If comparing -> Split screen. If explaining -> Single wide shot.
-    
-    [Prompt Structure to Generate]
-    "Flat 2D vector art. Stickman character in [Pose]. Background: [Elements]. Text at bottom: '[한국어 메인 타이틀]'. No speech bubbles."
+    "C. 2D Stickman 전용": """
+    - Flat vector, clean stickman.
+    - 말풍선 절대 금지.
+    - 대본 구조에 따라:
+      * 비교면 Split Screen
+      * 스토리면 Single Scene
+    - 텍스트 오버레이 필수:
+      * 하단: 메인 타이틀(thumb_text)
+      * 상단: 선택적 서브 문구
     """
-}
+}

logic_image.py

@@ -1,6 +1,28 @@
 # logic_image.py
+import json
+import logging
 import re
 
+logger = logging.getLogger(__name__)
+
+
+class ImageExtractionError(RuntimeError):
+    """Raised when image bytes cannot be extracted from a model response."""
+
+
+def _summarize_response_structure(response):
+    if response is None:
+        return "response=None"
+    summary = {
+        "type": type(response).__name__,
+        "has_candidates": hasattr(response, "candidates"),
+        "has_content": hasattr(response, "content"),
+        "has_image": hasattr(response, "image"),
+        "has_images": hasattr(response, "images"),
+        "has_data": hasattr(response, "data"),
+    }
+    return ", ".join(f"{k}={v}" for k, v in summary.items())
+
 def _get_style_prompt(selected_style, custom_style_input, style_definitions):
     if selected_style == "직접 입력":
         return (custom_style_input or "").strip()
@@ -15,29 +37,113 @@ def _safe_extract_image_bytes(response):
     (모델/버전별로 응답 구조가 달라서 방어적으로 처리)
     """
     # candidates -> content -> parts -> inline_data.data 패턴
-    try:
-        cands = getattr(response, "candidates", None) or []
-        if not cands:
-            return None
-        content = getattr(cands[0], "content", None)
-        parts = getattr(content, "parts", None) or []
-        for p in parts:
-            inline = getattr(p, "inline_data", None)
-            if inline and getattr(inline, "data", None):
-                return inline.data
-    except:
-        pass
+    cands = getattr(response, "candidates", None) or []
+    if cands:
+        for cand in cands:
+            content = getattr(cand, "content", None)
+            parts = getattr(content, "parts", None) or []
+            for p in parts:
+                inline = getattr(p, "inline_data", None)
+                data = getattr(inline, "data", None) if inline else None
+                if data:
+                    return data
+            text_parts = [getattr(p, "text", None) for p in parts if getattr(p, "text", None)]
+            if text_parts:
+                snippet = re.sub(r"\s+", " ", " ".join(text_parts)).strip()[:200]
+                raise ImageExtractionError(f"텍스트만 반환되어 이미지가 없습니다. 텍스트 일부: {snippet}")
+        raise ImageExtractionError("이미지 파트가 없어 bytes를 추출할 수 없습니다.")
 
     # 혹시 response.image 같은 형태로 오는 경우
     for key in ["image", "images", "data"]:
-        try:
-            v = getattr(response, key, None)
-            if isinstance(v, (bytes, bytearray)):
-                return bytes(v)
-        except:
-            pass
+        v = getattr(response, key, None)
+        if isinstance(v, (bytes, bytearray)):
+            return bytes(v)
+
+    summary = _summarize_response_structure(response)
+    raise ImageExtractionError(f"이미지 bytes 추출 실패: {summary}")
+
+
+def _generate_thumbnail_texts(strategy_key, script_text, title_hint, client, text_model_id):
+    default_payload = {"top": "", "layout": "single", "left": "", "right": ""}
+    if strategy_key.startswith("A."):
+        instruction = """
+대본을 참고해서 썸네일용 짧은 문구 2개를 작성해.
+- 좌측 상단: 부정적/과거/약자 분위기의 짧은 문구 (6자 이내)
+- 우측 상단: 긍정적/미래/강자 분위기의 짧은 문구 (6자 이내)
+출력 형식(JSON ONLY):
+{"left": "...", "right": "..."}
+""".strip()
+    elif strategy_key.startswith("B."):
+        instruction = """
+대본을 참고해서 썸네일 상단에 들어갈 서브 문구를 작성해.
+- "속보/긴급/단독" 같은 톤
+- 6자 이내
+출력 형식(JSON ONLY):
+{"top": "..."}
+""".strip()
+    else:
+        instruction = """
+대본을 참고해서 썸네일 상단에 들어갈 서브 문구를 작성해.
+- 6자 이내 (없으면 빈 문자열)
+그리고 구성 유형을 선택해.
+- 비교/대조면 split
+- 스토리 흐름이면 single
+출력 형식(JSON ONLY):
+{"top": "...", "layout": "split|single"}
+""".strip()
 
-    return None
+    prompt = f"""
+너는 유튜브 썸네일 카피라이터야.
+
+[대본]
+{script_text[:8000]}
+
+[참고 제목]
+{title_hint}
+
+[요구사항]
+{instruction}
+""".strip()
+
+    try:
+        response = client.models.generate_content(model=text_model_id, contents=prompt)
+        text = (getattr(response, "text", "") or "").strip()
+    except Exception as exc:
+        logger.exception("썸네일 서브 문구 생성 실패")
+        raise RuntimeError("썸네일 서브 문구 생성에 실패했습니다.") from exc
+
+    payload = None
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError:
+        payload = None
+
+    if not isinstance(payload, dict):
+        payload = {}
+
+    merged = {**default_payload, **payload}
+    layout = str(merged.get("layout", "single")).lower().strip()
+    if layout not in {"split", "single"}:
+        layout = "single"
+    merged["layout"] = layout
+
+    if strategy_key.startswith("A."):
+        left_text = str(merged.get("left") or "").strip()
+        right_text = str(merged.get("right") or "").strip()
+        if not left_text:
+            left_text = "위기"
+        if not right_text:
+            right_text = "기회"
+        return {"left_text": left_text, "right_text": right_text}
+
+    if strategy_key.startswith("B."):
+        top_text = str(merged.get("top") or "").strip()
+        if not top_text:
+            top_text = "속보"
+        return {"top_text": top_text}
+
+    top_text = str(merged.get("top") or "").strip()
+    return {"top_text": top_text, "layout": merged["layout"]}
 
 def process_scene_task(
     index,
@@ -84,64 +190,117 @@ def process_scene_task(
 3) 화면 분할(Split Screen) 금지. 한 장면으로만 구성.
 4) 이미지에 글자/자막 넣지 마라. (텍스트 오버레이 금지)
 5) 최종 출력은 "프롬프트 한 덩어리 텍스트"만. JSON/마크다운/번호/제목 금지.
+6) 결과는 이미지 1장이어야 하며, 설명/분석 텍스트 출력 금지.
+7) 16:9 (1280x720) 비율로 생성.
 
 이제 프롬프트를 출력해.
 """.strip()
 
 
-    brain_res = client.models.generate_content(
-        model=text_model_id,
-        contents=brain_prompt
-    )
+    try:
+        brain_res = client.models.generate_content(
+            model=text_model_id,
+            contents=brain_prompt
+        )
+    except Exception as exc:
+        logger.exception("장면 프롬프트 생성 실패")
+        raise RuntimeError("장면 프롬프트 생성에 실패했습니다.") from exc
 
     # brain_res.text가 없을 수도 있어 방어
     final_prompt = getattr(brain_res, "text", None) or scene_text
     final_prompt = re.sub(r"\s+", " ", final_prompt).strip()
 
-    # 2) Painter: 프롬프트 -> 이미지 생성
-    #    google-genai 버전에 따라 generate_images / generate_content 둘 다 대응
-    img_bytes = None
-
-    # (A) generate_images가 있으면 우선 사용
-    if hasattr(client.models, "generate_images"):
-        try:
-            img_res = client.models.generate_images(
+    # 2) Painter: 썸네일과 동일한 방식으로 모델 타입에 맞춰 생성
+    uses_gemini_image = "gemini" in (image_model_id or "").lower()
+
+    last_scene_response = {"value": None}
+
+    def _render_scene_image(prompt_text):
+        contents = prompt_text
+        if reference_image is not None:
+            try:
+                from google.genai import types
+                import io
+                buf = io.BytesIO()
+                reference_image.save(buf, format="PNG")
+                ref_part = types.Part.from_bytes(data=buf.getvalue(), mime_type="image/png")
+                contents = [prompt_text, ref_part]
+            except Exception as exc:
+                logger.exception("참조 이미지 처리 실패")
+                raise RuntimeError("참조 이미지 처리에 실패했습니다.") from exc
+
+        if uses_gemini_image:
+            try:
+                from google.genai import types
+            except Exception as exc:
+                logger.exception("GenerateContentConfig 로드 실패")
+                raise RuntimeError("이미지 생성 설정을 불러오지 못했습니다.") from exc
+            img_res = client.models.generate_content(
                 model=image_model_id,
-                prompt=final_prompt
+                contents=contents,
+                config=types.GenerateContentConfig(
+                    response_modalities=["IMAGE"],
+                    image_config=types.ImageConfig(image_size="1K")
+                )
             )
-            # 응답 구조가 버전마다 달라서 최대한 방어적으로 추출
-            img_bytes = _safe_extract_image_bytes(img_res)
-        except:
-            img_bytes = None
+            last_scene_response["value"] = img_res
+            return _safe_extract_image_bytes(img_res)
 
-    # (B) 없으면 generate_content로 시도
-    if img_bytes is None:
-        try:
-            # reference_image가 있을 경우, 가능한 형태로 같이 전달 시도
-            contents = final_prompt
-            if reference_image is not None:
-                # genai.types.Part 가 있으면 그걸 사용
-                try:
-                    from google.genai import types
-                    import io
-                    buf = io.BytesIO()
-                    reference_image.save(buf, format="PNG")
-                    ref_part = types.Part.from_bytes(data=buf.getvalue(), mime_type="image/png")
-                    contents = [final_prompt, ref_part]
-                except:
-                    # types가 없으면 그냥 텍스트만
-                    contents = final_prompt
-
-            img_res = client.models.generate_content(
+        if hasattr(client.models, "generate_images"):
+            img_res = client.models.generate_images(
                 model=image_model_id,
-                contents=contents
+                prompt=prompt_text
             )
-            img_bytes = _safe_extract_image_bytes(img_res)
-        except:
-            img_bytes = None
+            last_scene_response["value"] = img_res
+            return _safe_extract_image_bytes(img_res)
+
+        raise RuntimeError(
+            "장면 이미지 생성에 실패했습니다. "
+            "모델/호출방식 불일치일 수 있습니다. "
+            "Gemini 이미지 모델은 generateContent, Imagen 모델은 generate_images를 사용합니다."
+        )
 
-    return index, final_prompt, img_bytes
-    def process_thumbnail_task(
+    try:
+        img_bytes = _render_scene_image(final_prompt)
+        return index, final_prompt, img_bytes
+    except ImageExtractionError as exc:
+        response = last_scene_response["value"]
+        prompt_feedback = getattr(response, "prompt_feedback", None)
+        finish_reason = None
+        candidates = getattr(response, "candidates", None) or []
+        if candidates:
+            finish_reason = getattr(candidates[0], "finish_reason", None)
+        logger.exception(
+            "장면 이미지 추출 실패 (1차) finish_reason=%s prompt_feedback=%s",
+            finish_reason,
+            prompt_feedback
+        )
+        if "텍스트만 반환" in str(exc):
+            fallback_prompt = f"""
+핵심 장면: {scene_text}
+16:9 (1280x720). 한 장면으로만 구성. 이미지 생성만 출력.
+""".strip()
+            try:
+                img_bytes = _render_scene_image(fallback_prompt)
+                return index, fallback_prompt, img_bytes
+            except ImageExtractionError:
+                raise
+        raise
+    except Exception as exc:
+        logger.exception("장면 이미지 생성 실패")
+        if uses_gemini_image:
+            raise RuntimeError(
+                "장면 이미지 생성에 실패했습니다. "
+                "모델/호출방식 불일치일 수 있습니다. "
+                "Gemini 이미지 모델은 generateContent 방식이 필요합니다."
+            ) from exc
+        raise RuntimeError(
+            "장면 이미지 생성에 실패했습니다. "
+            "모델/호출방식 불일치일 수 있습니다. "
+            "Imagen 계열 모델을 선택하거나 Gemini 이미지 모델을 선택하세요."
+        ) from exc
+
+def process_thumbnail_task(
     index,
     strategy_key,
     strategy_text,
@@ -151,7 +310,7 @@ def process_scene_task(
     text_model_id,
     image_model_id,
     aspect_ratio,
-    reference_image=None
+    reference_image=None,
 ):
     """
     return (idx, final_prompt, image_bytes)
@@ -176,43 +335,137 @@ def process_scene_task(
 
 [필수 조건]
 - 출력은 무조건 한국어만. 영어/로마자 금지.
-- 이미지 안에 글자/자막/배너/로고 절대 생성 금지.
-- 대신 텍스트를 나중에 넣을 수 있게 상단 또는 하단에 넓은 여백(안전영역)을 확보.
 - 특정 국가 상징 자동생성 금지: 태극기, 청와대, 국회의사당, 대통령, 훈장/휘장, 선거 포스터, 국기류 전부 금지.
 - 정치인을 실존 인물처럼 특정하지 말고, 익명 캐릭터/실루엣/상징적 연출로 처리.
 - 화면 분할은 전략에 포함된 경우에만 허용.
-- 화면비: {aspect_ratio}
+- 화면비: 16:9 (1280x720)
 - 최종 출력은 프롬프트 텍스트 1개만. (JSON/마크다운/번호 금지)
 """.strip()
 
-    brain_res = client.models.generate_content(model=text_model_id, contents=brain_prompt)
-    final_prompt = (getattr(brain_res, "text", "") or "").strip()
+    try:
+        brain_res = client.models.generate_content(model=text_model_id, contents=brain_prompt)
+        scene_prompt = (getattr(brain_res, "text", "") or "").strip()
+    except Exception as exc:
+        logger.exception("썸네일 프롬프트 생성 실패")
+        raise RuntimeError("썸네일 프롬프트 생성에 실패했습니다.") from exc
+
+    overlay_texts = _generate_thumbnail_texts(strategy_key, script_text, title_hint, client, text_model_id)
+
+    common_rules = f"""
+- 포맷: 16:9 (1280x720). 전체 프레임 유지, 크롭/잘림 금지.
+- 텍스트 오버레이 반드시 포함.
+- 폰트: 굵은 고딕, 흰 글씨 + 검정 스트로크, 높은 대비.
+- 상단: 짧은 서브 문구.
+- 하단 중앙: 메인 타이틀 \"{title_hint}\" 그대로 사용.
+""".strip()
 
-    # 2) Painter: Tab1과 동일한 방식으로 이미지 생성
-    img_bytes = None
+    if strategy_key.startswith("A."):
+        overlay_rules = f"""
+- 좌측 상단 문구: \"{overlay_texts['left_text']}\".
+- 우측 상단 문구: \"{overlay_texts['right_text']}\".
+- 하단 중앙 메인 타이틀: \"{title_hint}\".
+""".strip()
+    elif strategy_key.startswith("B."):
+        overlay_rules = f"""
+- 상단 서브 문구: \"{overlay_texts['top_text']}\".
+- 하단 중앙 메인 타이틀: \"{title_hint}\".
+""".strip()
+    else:
+        layout_text = "Split Screen" if overlay_texts["layout"] == "split" else "Single Scene"
+        overlay_rules = f"""
+- 구성: {layout_text}.
+- 상단 서브 문구: \"{overlay_texts['top_text']}\".
+- 하단 중앙 메인 ��이틀: \"{title_hint}\".
+""".strip()
 
-    # (A) generate_images 우선
-    if hasattr(client.models, "generate_images"):
-        try:
-            img_res = client.models.generate_images(
-                model=image_model_id,
-                prompt=final_prompt
-            )
-            img_bytes = _safe_extract_image_bytes(img_res)
-        except:
-            img_bytes = None
+    final_prompt = f"""
+[전략 설명]
+{strategy_text}
 
-    # (B) fallback: generate_content
-    if img_bytes is None:
-        try:
-            contents = final_prompt
+[장면 구성]
+{scene_prompt}
+
+[공통 규칙]
+{common_rules}
+
+[텍스트 배치]
+{overlay_rules}
+""".strip()
+
+    # 2) Painter: 모델 특성에 맞게 이미지 생성
+    uses_gemini_image = "gemini" in (image_model_id or "").lower()
+
+    last_response = {"value": None}
+
+    def _render_image(prompt_text):
+        if uses_gemini_image:
+            try:
+                from google.genai import types
+            except Exception as exc:
+                logger.exception("GenerateContentConfig 로드 실패")
+                raise RuntimeError("이미지 생성 설정을 불러오지 못했습니다.") from exc
             img_res = client.models.generate_content(
                 model=image_model_id,
-                contents=contents
+                contents=prompt_text,
+                config=types.GenerateContentConfig(
+                    response_modalities=["IMAGE"],
+                    image_config=types.ImageConfig(image_size="1K")
+                )
             )
-            img_bytes = _safe_extract_image_bytes(img_res)
-        except:
-            img_bytes = None
-
-    return index, final_prompt, img_bytes
+            last_response["value"] = img_res
+            return _safe_extract_image_bytes(img_res)
+        if hasattr(client.models, "generate_images"):
+            img_res = client.models.generate_images(
+                model=image_model_id,
+                prompt=prompt_text
+            )
+            last_response["value"] = img_res
+            return _safe_extract_image_bytes(img_res)
+        raise RuntimeError(
+            "썸네일 이미지 생성에 실패했습니다. "
+            "모델/호출방식 불일치일 수 있습니다. "
+            "Gemini 이미지 모델은 generateContent, Imagen 모델은 generate_images를 사용합니다."
+        )
 
+    try:
+        img_bytes = _render_image(final_prompt)
+        return index, final_prompt, img_bytes
+    except ImageExtractionError as exc:
+        response = last_response["value"]
+        prompt_feedback = getattr(response, "prompt_feedback", None)
+        finish_reason = None
+        candidates = getattr(response, "candidates", None) or []
+        if candidates:
+            finish_reason = getattr(candidates[0], "finish_reason", None)
+        logger.exception(
+            "썸네일 이미지 추출 실패 (1차) finish_reason=%s prompt_feedback=%s",
+            finish_reason,
+            prompt_feedback
+        )
+        if not strategy_key.startswith("B."):
+            raise
+        fallback_prompt = f"""
+16:9 유튜브 썸네일. 현실 다큐 뉴스 사진 배경.
+전경에 2D 스틱맨이 충격/강조 리액션.
+텍스트 오버레이 포함: 상단 \"{overlay_texts.get('top_text', '')}\",
+하단 중앙 \"{title_hint}\". 흰 글씨 + 검정 스트로크, 굵은 고딕.
+""".strip()
+        try:
+            img_bytes = _render_image(fallback_prompt)
+            return index, fallback_prompt, img_bytes
+        except ImageExtractionError as retry_exc:
+            logger.exception("썸네일 이미지 추출 실패 (폴백)")
+            raise retry_exc from exc
+    except Exception as exc:
+        logger.exception("썸네일 이미지 생성 실패")
+        if uses_gemini_image:
+            raise RuntimeError(
+                "썸네일 이미지 생성에 실패했습니다. "
+                "모델/호출방식 불일치일 수 있습니다. "
+                "Gemini 이미지 모델은 generateContent 방식이 필요합니다."
+            ) from exc
+        raise RuntimeError(
+            "썸네일 이미지 생성에 실패했습니다. "
+            "모델/호출방식 불일치일 수 있습니다. "
+            "Imagen 계열 모델을 선택하거나 Gemini 이미지 모델을 선택하세요."
+        ) from exc

utils.py

@@ -20,4 +20,19 @@ def group_sentences(text, target_sec=10):
 def get_smart_filename(index, text):
     clean_text = re.sub(r'[\\/*?:"<>|]', "", text).strip()
     name_part = clean_text[:12] if len(clean_text) <= 12 else f"{clean_text[:6]}~{clean_text[-4:]}"
-    return f"{index+1:02d}_{name_part}.png"
+    return f"{index+1:02d}_{name_part}.png"
+
+def make_scene_snippet(text, head_len=10, tail_len=10, max_len=60):
+    clean_text = " ".join((text or "").strip().split())
+    clean_text = re.sub(r'[\\/*?:"<>|]', "", clean_text)
+    clean_text = re.sub(r"[^0-9A-Za-z가-힣\s.~]", " ", clean_text)
+    clean_text = re.sub(r"[.]{2,}", ".", clean_text)
+    clean_text = re.sub(r"\s+", " ", clean_text).strip()
+    if not clean_text:
+        return "scene"
+    if len(clean_text) <= head_len + tail_len + 1:
+        snippet = clean_text
+    else:
+        snippet = f"{clean_text[:head_len]}~{clean_text[-tail_len:]}"
+    snippet = re.sub(r"\s+", " ", snippet).strip()
+    return snippet[:max_len].rstrip(" .")