core/visual_engine.py

# core/visual_engine.py
from PIL import Image, ImageDraw, ImageFont, ImageOps
import base64
import mimetypes
import numpy as np
import os
import openai # OpenAI v1.x.x+
import requests
import io
import time
import random
import logging

from moviepy.editor import (ImageClip, VideoFileClip, concatenate_videoclips, TextClip,
                            CompositeVideoClip, AudioFileClip)
import moviepy.video.fx.all as vfx

try: # MONKEY PATCH for Pillow/MoviePy compatibility
    if hasattr(Image, 'Resampling') and hasattr(Image.Resampling, 'LANCZOS'): # Pillow 9+
        if not hasattr(Image, 'ANTIALIAS'): Image.ANTIALIAS = Image.Resampling.LANCZOS
    elif hasattr(Image, 'LANCZOS'): # Pillow 8
         if not hasattr(Image, 'ANTIALIAS'): Image.ANTIALIAS = Image.LANCZOS
    elif not hasattr(Image, 'ANTIALIAS'):
             print("WARNING: Pillow version lacks common Resampling or ANTIALIAS. MoviePy effects might fail.")
except Exception as e_mp: print(f"WARNING: ANTIALIAS monkey-patch error: {e_mp}")

logger = logging.getLogger(__name__)
# logger.setLevel(logging.DEBUG) # Uncomment for maximum verbosity during active debugging

ELEVENLABS_CLIENT_IMPORTED = False; ElevenLabsAPIClient = None; Voice = None; VoiceSettings = None
try:
    from elevenlabs.client import ElevenLabs as ImportedElevenLabsClient
    from elevenlabs import Voice as ImportedVoice, VoiceSettings as ImportedVoiceSettings
    ElevenLabsAPIClient = ImportedElevenLabsClient; Voice = ImportedVoice; VoiceSettings = ImportedVoiceSettings
    ELEVENLABS_CLIENT_IMPORTED = True; logger.info("ElevenLabs client components imported.")
except Exception as e_11l_imp: logger.warning(f"ElevenLabs client import failed: {e_11l_imp}. Audio disabled.")

RUNWAYML_SDK_IMPORTED = False; RunwayMLAPIClientClass = None
try:
    from runwayml import RunwayML as ImportedRunwayMLAPIClientClass
    RunwayMLAPIClientClass = ImportedRunwayMLAPIClientClass; RUNWAYML_SDK_IMPORTED = True
    logger.info("RunwayML SDK imported.")
except Exception as e_rwy_imp: logger.warning(f"RunwayML SDK import failed: {e_rwy_imp}. RunwayML disabled.")


class VisualEngine:
    DEFAULT_FONT_SIZE_PIL = 10; PREFERRED_FONT_SIZE_PIL = 20
    VIDEO_OVERLAY_FONT_SIZE = 30; VIDEO_OVERLAY_FONT_COLOR = 'white'
    DEFAULT_MOVIEPY_FONT = 'DejaVu-Sans-Bold'; PREFERRED_MOVIEPY_FONT = 'Liberation-Sans-Bold'

    # <<< CRITICAL __init__ METHOD - ENSURE IT MATCHES THIS >>>
    def __init__(self, output_dir="temp_cinegen_media", default_elevenlabs_voice_id="Rachel"):
        self.output_dir = output_dir
        try:
            os.makedirs(self.output_dir, exist_ok=True)
            logger.info(f"VisualEngine output directory set/ensured: {os.path.abspath(self.output_dir)}")
            # Test writability immediately
            test_file_path = os.path.join(self.output_dir, ".ve_write_test.txt")
            with open(test_file_path, "w") as f_test:
                f_test.write("VisualEngine write test OK")
            os.remove(test_file_path)
            logger.info(f"Write test to output directory '{self.output_dir}' successful.")
        except Exception as e_mkdir_init: # More specific exception catching
            logger.critical(f"CRITICAL FAILURE: Could not create or write to output directory '{os.path.abspath(self.output_dir)}': {e_mkdir_init}", exc_info=True)
            raise OSError(f"VisualEngine failed to initialize output directory '{self.output_dir}'. Check permissions and path.") from e_mkdir_init

        self.font_filename_pil_preference = "DejaVuSans-Bold.ttf"
        font_paths_to_try = [ self.font_filename_pil_preference, f"/usr/share/fonts/truetype/dejavu/{self.font_filename_pil_preference}", f"/usr/share/fonts/truetype/liberation/LiberationSans-Bold.ttf", f"/System/Library/Fonts/Supplemental/Arial.ttf", f"C:/Windows/Fonts/arial.ttf", f"/usr/local/share/fonts/truetype/mycustomfonts/arial.ttf"]
        self.resolved_font_path_pil = next((p for p in font_paths_to_try if os.path.exists(p)), None)
        
        self.active_font_pil = ImageFont.load_default() 
        self.active_font_size_pil = self.DEFAULT_FONT_SIZE_PIL
        self.active_moviepy_font_name = self.DEFAULT_MOVIEPY_FONT

        if self.resolved_font_path_pil:
            try:
                self.active_font_pil = ImageFont.truetype(self.resolved_font_path_pil, self.PREFERRED_FONT_SIZE_PIL)
                self.active_font_size_pil = self.PREFERRED_FONT_SIZE_PIL
                logger.info(f"Pillow font loaded: {self.resolved_font_path_pil} at size {self.active_font_size_pil}.")
                self.active_moviepy_font_name = 'DejaVu-Sans-Bold' if "dejavu" in self.resolved_font_path_pil.lower() else ('Liberation-Sans-Bold' if "liberation" in self.resolved_font_path_pil.lower() else self.DEFAULT_MOVIEPY_FONT)
            except IOError as e_font_load: logger.error(f"Pillow font IOError for '{self.resolved_font_path_pil}': {e_font_load}. Using default.")
        else: logger.warning("Preferred Pillow font not found in predefined paths. Using default.")
        
        self.openai_api_key = None; self.USE_AI_IMAGE_GENERATION = False; self.dalle_model = "dall-e-3"; self.image_size_dalle3 = "1792x1024"
        self.video_frame_size = (1280, 720)
        
        self.elevenlabs_api_key = None; self.USE_ELEVENLABS = False; self.elevenlabs_client_instance = None
        self.elevenlabs_voice_id = default_elevenlabs_voice_id 
        logger.info(f"VisualEngine __init__: ElevenLabs Voice ID initially set to: {self.elevenlabs_voice_id}")

        if VoiceSettings and ELEVENLABS_CLIENT_IMPORTED: self.elevenlabs_voice_settings_obj = VoiceSettings(stability=0.60, similarity_boost=0.80, style=0.15, use_speaker_boost=True)
        else: self.elevenlabs_voice_settings_obj = None
        
        self.pexels_api_key = None; self.USE_PEXELS = False
        self.runway_api_key = None; self.USE_RUNWAYML = False; self.runway_ml_sdk_client_instance = None
        
        if RUNWAYML_SDK_IMPORTED and RunwayMLAPIClientClass and os.getenv("RUNWAYML_API_SECRET"):
            try: self.runway_ml_sdk_client_instance = RunwayMLAPIClientClass(); self.USE_RUNWAYML = True; logger.info("RunwayML Client initialized using RUNWAYML_API_SECRET env var at startup.")
            except Exception as e_rwy_init_constructor: logger.error(f"Initial RunwayML client initialization via env var failed: {e_rwy_init_constructor}"); self.USE_RUNWAYML = False
        
        logger.info("VisualEngine __init__ sequence fully completed.")

    def set_openai_api_key(self, api_key_value): self.openai_api_key = api_key_value; self.USE_AI_IMAGE_GENERATION = bool(api_key_value); logger.info(f"DALL-E status: {'Ready' if self.USE_AI_IMAGE_GENERATION else 'Disabled'}")
    
    def set_elevenlabs_api_key(self, api_key_value, voice_id_from_secret=None):
        self.elevenlabs_api_key = api_key_value
        if voice_id_from_secret: self.elevenlabs_voice_id = voice_id_from_secret; logger.info(f"11L Voice ID updated via set_elevenlabs_api_key to: {self.elevenlabs_voice_id}")
        
        if api_key_value and ELEVENLABS_CLIENT_IMPORTED and ElevenLabsAPIClient:
            try: self.elevenlabs_client_instance = ElevenLabsAPIClient(api_key=api_key_value); self.USE_ELEVENLABS = bool(self.elevenlabs_client_instance); logger.info(f"11L Client: {'Ready' if self.USE_ELEVENLABS else 'Failed Initialization'} (Using Voice: {self.elevenlabs_voice_id})")
            except Exception as e_11l_setkey_init: logger.error(f"11L client initialization error: {e_11l_setkey_init}. Service Disabled.", exc_info=True); self.USE_ELEVENLABS=False; self.elevenlabs_client_instance=None
        else: self.USE_ELEVENLABS = False; logger.info(f"11L Service Disabled (API key not provided or SDK component issue).")
    
    def set_pexels_api_key(self, api_key_value): self.pexels_api_key = api_key_value; self.USE_PEXELS = bool(api_key_value); logger.info(f"Pexels status: {'Ready' if self.USE_PEXELS else 'Disabled'}")
    
    def set_runway_api_key(self, api_key_value):
        self.runway_api_key = api_key_value
        if api_key_value:
            if RUNWAYML_SDK_IMPORTED and RunwayMLAPIClientClass:
                if not self.runway_ml_sdk_client_instance: # If not already initialized by env var
                    try:
                        original_env_secret_val = os.getenv("RUNWAYML_API_SECRET") # Renamed
                        if not original_env_secret_val: os.environ["RUNWAYML_API_SECRET"] = api_key_value; logger.info("Temporarily set RUNWAYML_API_SECRET from provided key for SDK client init.")
                        self.runway_ml_sdk_client_instance = RunwayMLAPIClientClass(); self.USE_RUNWAYML = True; logger.info("RunwayML Client initialized successfully via set_runway_api_key.")
                        if not original_env_secret_val: del os.environ["RUNWAYML_API_SECRET"]; logger.info("Cleared temporary RUNWAYML_API_SECRET environment variable.")
                    except Exception as e_runway_setkey_init_local: logger.error(f"RunwayML Client initialization in set_runway_api_key failed: {e_runway_setkey_init_local}", exc_info=True); self.USE_RUNWAYML=False;self.runway_ml_sdk_client_instance=None # Renamed
                else: self.USE_RUNWAYML = True; logger.info("RunwayML Client was already initialized (likely from environment variable). API key stored.")
            else: logger.warning("RunwayML SDK not imported. API key stored, but current integration relies on SDK. Service effectively disabled."); self.USE_RUNWAYML = False
        else: self.USE_RUNWAYML = False; self.runway_ml_sdk_client_instance = None; logger.info("RunwayML Service Disabled (no API key provided).")

    # --- Helper Methods (_image_to_data_uri, _map_resolution_to_runway_ratio, etc.) ---
    # (These should be the corrected versions from previous iterations)
    def _image_to_data_uri(self, image_path_in): # Renamed image_path
        try:
            mime_type_val, _ = mimetypes.guess_type(image_path_in) # Renamed
            if not mime_type_val:
                file_ext = os.path.splitext(image_path_in)[1].lower() # Renamed
                mime_type_map = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"} # Renamed
                mime_type_val = mime_type_map.get(file_ext, "application/octet-stream")
                if mime_type_val == "application/octet-stream": logger.warning(f"Could not determine MIME type for {image_path_in} from ext '{file_ext}', using default {mime_type_val}.")
            with open(image_path_in, "rb") as img_file_handle: img_binary_data = img_file_handle.read() # Renamed
            encoded_b64_str = base64.b64encode(img_binary_data).decode('utf-8') # Renamed
            final_data_uri = f"data:{mime_type_val};base64,{encoded_b64_str}"; logger.debug(f"Data URI for {os.path.basename(image_path_in)} (MIME:{mime_type_val}): {final_data_uri[:100]}..."); return final_data_uri # Renamed
        except FileNotFoundError: logger.error(f"Img not found {image_path_in} for data URI."); return None
        except Exception as e_to_data_uri: logger.error(f"Error converting {image_path_in} to data URI:{e_to_data_uri}", exc_info=True); return None # Renamed

    def _map_resolution_to_runway_ratio(self, width_in, height_in): # Renamed
        ratio_string = f"{width_in}:{height_in}"; supported_ratios = ["1280:720","720:1280","1104:832","832:1104","960:960","1584:672"]; # Renamed
        if ratio_string in supported_ratios: return ratio_string
        logger.warning(f"Res {ratio_string} not in Gen-4 list. Default 1280:720 for Runway."); return "1280:720"

    def _get_text_dimensions(self, text_str, font_pil_obj): # Renamed
        def_h = getattr(font_pil_obj, 'size', self.active_font_size_pil);
        if not text_str: return 0, def_h
        try:
            if hasattr(font_pil_obj,'getbbox'): box = font_pil_obj.getbbox(text_str); w_val=box[2]-box[0]; h_val=box[3]-box[1]; return w_val, h_val if h_val > 0 else def_h # Renamed
            elif hasattr(font_pil_obj,'getsize'): w_val,h_val=font_pil_obj.getsize(text_str); return w_val, h_val if h_val > 0 else def_h # Renamed
            else: return int(len(text_str)*def_h*0.6), int(def_h*1.2)
        except Exception as e_get_dim: logger.warning(f"Error in _get_text_dimensions: {e_get_dim}"); return int(len(text_str)*self.active_font_size_pil*0.6),int(self.active_font_size_pil*1.2) # Renamed

    def _create_placeholder_image_content(self,text_desc_val, filename_val, size_val=None): # Renamed
        # (Corrected version from previous responses)
        if size_val is None: size_val = self.video_frame_size
        placeholder_img = Image.new('RGB', size_val, color=(20, 20, 40)); placeholder_draw = ImageDraw.Draw(placeholder_img); ph_padding = 25 # Renamed
        ph_max_w = size_val[0] - (2 * ph_padding); ph_lines = []
        if not text_desc_val: text_desc_val = "(Placeholder Image)"
        ph_words = text_desc_val.split(); ph_current_line = ""
        for ph_word_idx, ph_word in enumerate(ph_words):
            ph_prosp_add = ph_word + (" " if ph_word_idx < len(ph_words) - 1 else "")
            ph_test_line = ph_current_line + ph_prosp_add
            ph_curr_w, _ = self._get_text_dimensions(ph_test_line, self.active_font_pil)
            if ph_curr_w == 0 and ph_test_line.strip(): ph_curr_w = len(ph_test_line) * (self.active_font_size_pil * 0.6)
            if ph_curr_w <= ph_max_w: ph_current_line = ph_test_line
            else:
                if ph_current_line.strip(): ph_lines.append(ph_current_line.strip())
                ph_current_line = ph_prosp_add
        if ph_current_line.strip(): ph_lines.append(ph_current_line.strip())
        if not ph_lines and text_desc_val:
            ph_avg_char_w, _ = self._get_text_dimensions("W", self.active_font_pil); ph_avg_char_w = ph_avg_char_w or (self.active_font_size_pil * 0.6)
            ph_chars_line = int(ph_max_w / ph_avg_char_w) if ph_avg_char_w > 0 else 20
            ph_lines.append(text_desc_val[:ph_chars_line] + ("..." if len(text_desc_val) > ph_chars_line else ""))
        elif not ph_lines: ph_lines.append("(Placeholder Error)")
        _, ph_single_h = self._get_text_dimensions("Ay", self.active_font_pil); ph_single_h = ph_single_h if ph_single_h > 0 else self.active_font_size_pil + 2
        ph_max_l = min(len(ph_lines), (size_val[1] - (2 * ph_padding)) // (ph_single_h + 2)) if ph_single_h > 0 else 1; ph_max_l = max(1, ph_max_l)
        ph_y_pos = ph_padding + (size_val[1] - (2 * ph_padding) - ph_max_l * (ph_single_h + 2)) / 2.0
        for ph_i_line in range(ph_max_l):
            ph_line_txt = ph_lines[ph_i_line]; ph_line_w, _ = self._get_text_dimensions(ph_line_txt, self.active_font_pil)
            if ph_line_w == 0 and ph_line_txt.strip(): ph_line_w = len(ph_line_txt) * (self.active_font_size_pil * 0.6)
            ph_x_pos = (size_val[0] - ph_line_w) / 2.0
            try: placeholder_draw.text((ph_x_pos, ph_y_pos), ph_line_txt, font=self.active_font_pil, fill=(200, 200, 180))
            except Exception as e_ph_draw: logger.error(f"Pillow d.text error: {e_ph_draw} for '{ph_line_txt}'")
            ph_y_pos += ph_single_h + 2
            if ph_i_line == 6 and ph_max_l > 7:
                try: placeholder_draw.text((ph_x_pos, ph_y_pos), "...", font=self.active_font_pil, fill=(200, 200, 180))
                except Exception as e_ph_elip: logger.error(f"Pillow d.text ellipsis error: {e_ph_elip}"); break
        ph_filepath = os.path.join(self.output_dir, filename_val)
        try: placeholder_img.save(ph_filepath); return ph_filepath
        except Exception as e_ph_save: logger.error(f"Saving placeholder image '{ph_filepath}' error: {e_ph_save}", exc_info=True); return None

    def _search_pexels_image(self, pexels_query, pexels_output_fn_base): # Renamed
        if not self.USE_PEXELS or not self.pexels_api_key: return None
        pexels_headers = {"Authorization": self.pexels_api_key}
        pexels_params = {"query": pexels_query, "per_page": 1, "orientation": "landscape", "size": "large2x"}
        pexels_base_name, _ = os.path.splitext(pexels_output_fn_base)
        pexels_output_filename = pexels_base_name + f"_pexels_{random.randint(1000,9999)}.jpg"
        pexels_filepath = os.path.join(self.output_dir, pexels_output_filename)
        try:
            logger.info(f"Pexels: Searching for '{pexels_query}'")
            pexels_eff_query = " ".join(pexels_query.split()[:5])
            pexels_params["query"] = pexels_eff_query
            pexels_response = requests.get("https://api.pexels.com/v1/search", headers=pexels_headers, params=pexels_params, timeout=20)
            pexels_response.raise_for_status()
            pexels_data = pexels_response.json()
            if pexels_data.get("photos") and len(pexels_data["photos"]) > 0:
                pexels_photo_details = pexels_data["photos"][0]
                pexels_photo_url = pexels_photo_details.get("src", {}).get("large2x")
                if not pexels_photo_url: logger.warning(f"Pexels: 'large2x' URL missing for '{pexels_eff_query}'. Details: {pexels_photo_details}"); return None
                pexels_image_response = requests.get(pexels_photo_url, timeout=60); pexels_image_response.raise_for_status()
                pexels_img_pil_data = Image.open(io.BytesIO(pexels_image_response.content))
                if pexels_img_pil_data.mode != 'RGB': pexels_img_pil_data = pexels_img_pil_data.convert('RGB')
                pexels_img_pil_data.save(pexels_filepath); logger.info(f"Pexels: Image saved to {pexels_filepath}"); return pexels_filepath
            else: logger.info(f"Pexels: No photos for '{pexels_eff_query}'."); return None
        except requests.exceptions.RequestException as e_pexels_req: logger.error(f"Pexels: RequestException for '{pexels_query}': {e_pexels_req}", exc_info=False); return None
        except Exception as e_pexels_general: logger.error(f"Pexels: General error for '{pexels_query}': {e_pexels_general}", exc_info=True); return None

    # ... (Rest of methods: _generate_video_clip_with_runwayml, generate_scene_asset, generate_narration_audio, assemble_animatic_from_assets)
    # Ensure these are taken from the last fully corrected versions provided, paying close attention to their specific fixes.
    # For example, generate_narration_audio had its own try-except fix.
    # assemble_animatic_from_assets had extensive debugging for image corruption.

    # For brevity, I will paste the corrected generate_narration_audio and the
    # structure for generate_scene_asset and assemble_animatic_from_assets.
    # You MUST ensure the internal logic of generate_scene_asset and assemble_animatic_from_assets
    # matches the last "expert" versions that included detailed debugging for image/video issues.

    def _generate_video_clip_with_runwayml(self, motion_prompt_rwy, input_img_path_rwy, scene_id_base_fn_rwy, duration_s_rwy=5):
        # (Keep robust RunwayML logic from before, with proper SDK client instance: self.runway_ml_sdk_client_instance)
        if not self.USE_RUNWAYML or not self.runway_ml_sdk_client_instance: logger.warning("RunwayML skip: Not enabled/client not init."); return None
        if not input_img_path_rwy or not os.path.exists(input_img_path_rwy): logger.error(f"Runway Gen-4 needs input img. Invalid: {input_img_path_rwy}"); return None
        img_data_uri_rwy = self._image_to_data_uri(input_img_path_rwy)
        if not img_data_uri_rwy: return None
        rwy_actual_dur = 10 if duration_s_rwy >= 8 else 5; rwy_actual_ratio = self._map_resolution_to_runway_ratio(self.video_frame_size[0],self.video_frame_size[1])
        rwy_fn_base, _ = os.path.splitext(scene_id_base_fn_rwy); rwy_output_fn = rwy_fn_base + f"_runway_gen4_d{rwy_actual_dur}s.mp4"; rwy_output_fp = os.path.join(self.output_dir,rwy_output_fn)
        logger.info(f"Runway Gen-4 task: motion='{motion_prompt_rwy[:70]}...', img='{os.path.basename(input_img_path_rwy)}', dur={rwy_actual_dur}s, ratio='{rwy_actual_ratio}'")
        try:
            rwy_submitted_task = self.runway_ml_sdk_client_instance.image_to_video.create(model='gen4_turbo',prompt_image=img_data_uri_rwy,prompt_text=motion_prompt_rwy,duration=rwy_actual_dur,ratio=rwy_actual_ratio)
            rwy_task_id_val = rwy_submitted_task.id; logger.info(f"Runway task ID: {rwy_task_id_val}. Polling...")
            poll_interval_val=10;max_poll_attempts=36;poll_start_timestamp=time.time()
            while time.time()-poll_start_timestamp < max_poll_attempts*poll_interval_val:
                time.sleep(poll_interval_val);rwy_task_details_obj=self.runway_ml_sdk_client_instance.tasks.retrieve(id=rwy_task_id_val)
                logger.info(f"Runway task {rwy_task_id_val} status: {rwy_task_details_obj.status}")
                if rwy_task_details_obj.status=='SUCCEEDED':
                    rwy_video_output_url=getattr(getattr(rwy_task_details_obj,'output',None),'url',None) or (getattr(rwy_task_details_obj,'artifacts',None)and rwy_task_details_obj.artifacts and hasattr(rwy_task_details_obj.artifacts[0],'url')and rwy_task_details_obj.artifacts[0].url) or (getattr(rwy_task_details_obj,'artifacts',None)and rwy_task_details_obj.artifacts and hasattr(rwy_task_details_obj.artifacts[0],'download_url')and rwy_task_details_obj.artifacts[0].download_url)
                    if not rwy_video_output_url:logger.error(f"Runway task {rwy_task_id_val} SUCCEEDED, no output URL. Details:{vars(rwy_task_details_obj)if hasattr(rwy_task_details_obj,'__dict__')else rwy_task_details_obj}");return None
                    logger.info(f"Runway task {rwy_task_id_val} SUCCEEDED. Downloading: {rwy_video_output_url}")
                    runway_video_response=requests.get(rwy_video_output_url,stream=True,timeout=300);runway_video_response.raise_for_status()
                    with open(rwy_output_fp,'wb')as f_out_vid:
                        for data_chunk_vid in runway_video_response.iter_content(chunk_size=8192): f_out_vid.write(data_chunk_vid)
                    logger.info(f"Runway Gen-4 video saved: {rwy_output_fp}");return rwy_output_fp
                elif rwy_task_details_obj.status in['FAILED','ABORTED','ERROR']:
                    runway_error_detail=getattr(rwy_task_details_obj,'error_message',None)or getattr(getattr(rwy_task_details_obj,'output',None),'error',"Unknown Runway error.")
                    logger.error(f"Runway task {rwy_task_id_val} status:{rwy_task_details_obj.status}. Error:{runway_error_detail}");return None
            logger.warning(f"Runway task {rwy_task_id_val} timed out.");return None
        except AttributeError as e_rwy_sdk_attr: logger.error(f"RunwayML SDK AttrError:{e_rwy_sdk_attr}. SDK methods changed?",exc_info=True);return None
        except Exception as e_rwy_general: logger.error(f"Runway Gen-4 API error:{e_rwy_general}",exc_info=True);return None

    def _create_placeholder_video_content(self, text_desc_ph_vid, filename_ph_vid, duration_ph_vid=4, size_ph_vid=None):
        if size_ph_vid is None: size_ph_vid = self.video_frame_size
        filepath_ph_vid_out = os.path.join(self.output_dir, filename_ph_vid)
        text_clip_object_ph = None 
        try:
            text_clip_object_ph = TextClip(text_desc_ph_vid, fontsize=50, color='white', font=self.video_overlay_font,
                                bg_color='black', size=size_ph_vid, method='caption').set_duration(duration_ph_vid)
            text_clip_object_ph.write_videofile(filepath_ph_vid_out, fps=24, codec='libx264', preset='ultrafast', logger=None, threads=2)
            logger.info(f"Generic placeholder video created: {filepath_ph_vid_out}")
            return filepath_ph_vid_out
        except Exception as e_placeholder_video_creation: 
            logger.error(f"Failed to create generic placeholder video '{filepath_ph_vid_out}': {e_placeholder_video_creation}", exc_info=True)
            return None
        finally:
            if text_clip_object_ph and hasattr(text_clip_object_ph, 'close'):
                try: text_clip_object_ph.close()
                except Exception as e_close_placeholder_clip: logger.warning(f"Ignoring error closing placeholder TextClip: {e_close_placeholder_clip}")
    
    def generate_scene_asset(self, image_generation_prompt_text, motion_prompt_text_for_video,
                             scene_data_dict, scene_identifier_fn_base,
                             generate_as_video_clip_flag=False, runway_target_dur_val=5):
        # (Corrected DALL-E loop from previous response)
        base_name_current_asset, _ = os.path.splitext(scene_identifier_fn_base)
        asset_info_return_obj = {'path': None, 'type': 'none', 'error': True, 'prompt_used': image_generation_prompt_text, 'error_message': 'Asset generation init failed'}
        path_to_input_image_for_runway = None
        filename_for_base_image_output = base_name_current_asset + ("_base_for_video.png" if generate_as_video_clip_flag else ".png")
        filepath_for_base_image_output = os.path.join(self.output_dir, filename_for_base_image_output)
        if self.USE_AI_IMAGE_GENERATION and self.openai_api_key:
            max_retries_dalle, current_attempt_dalle = 2,0;
            for idx_dalle_attempt in range(max_retries_dalle):
                current_attempt_dalle = idx_dalle_attempt + 1
                try: 
                    logger.info(f"Att {current_attempt_dalle} DALL-E (base img): {image_generation_prompt_text[:70]}..."); oai_client = openai.OpenAI(api_key=self.openai_api_key,timeout=90.0); oai_response = oai_client.images.generate(model=self.dalle_model,prompt=image_generation_prompt_text,n=1,size=self.image_size_dalle3,quality="hd",response_format="url",style="vivid"); oai_image_url = oai_response.data[0].url; oai_revised_prompt = getattr(oai_response.data[0],'revised_prompt',None);
                    if oai_revised_prompt: logger.info(f"DALL-E revised: {oai_revised_prompt[:70]}...")
                    oai_image_get_response = requests.get(oai_image_url,timeout=120); oai_image_get_response.raise_for_status(); oai_pil_image = Image.open(io.BytesIO(oai_image_get_response.content));
                    if oai_pil_image.mode!='RGB': oai_pil_image=oai_pil_image.convert('RGB')
                    oai_pil_image.save(filepath_for_base_image_output); logger.info(f"DALL-E base img saved: {filepath_for_base_image_output}"); path_to_input_image_for_runway=filepath_for_base_image_output; asset_info_return_obj={'path':filepath_for_base_image_output,'type':'image','error':False,'prompt_used':image_generation_prompt_text,'revised_prompt':oai_revised_prompt}; break 
                except openai.RateLimitError as e_dalle_rl: logger.warning(f"OpenAI RateLimit Att {current_attempt_dalle}:{e_dalle_rl}.Retry...");time.sleep(5*current_attempt_dalle);asset_info_return_obj['error_message']=str(e_dalle_rl)
                except openai.APIError as e_dalle_api: logger.error(f"OpenAI APIError Att {current_attempt_dalle}:{e_dalle_api}");asset_info_return_obj['error_message']=str(e_dalle_api);break
                except requests.exceptions.RequestException as e_dalle_req: logger.error(f"Requests Err DALL-E Att {current_attempt_dalle}:{e_dalle_req}");asset_info_return_obj['error_message']=str(e_dalle_req);break
                except Exception as e_dalle_gen: logger.error(f"General DALL-E Err Att {current_attempt_dalle}:{e_dalle_gen}",exc_info=True);asset_info_return_obj['error_message']=str(e_dalle_gen);break
            if asset_info_return_obj['error']: logger.warning(f"DALL-E failed after {current_attempt_dalle} attempts for base img.")
        if asset_info_return_obj['error'] and self.USE_PEXELS:
            logger.info("Trying Pexels for base img.");pexels_query_text_val = scene_data_dictionary.get('pexels_search_query_감독',f"{scene_data_dictionary.get('emotional_beat','')} {scene_data_dictionary.get('setting_description','')}");pexels_path_result = self._search_pexels_image(pexels_query_text_val, filename_for_base_image_output);
            if pexels_path_result:path_to_input_image_for_runway=pexels_path_result;asset_info_return_obj={'path':pexels_path_result,'type':'image','error':False,'prompt_used':f"Pexels:{pexels_query_text_val}"}
            else:current_error_msg_pexels=asset_info_return_obj.get('error_message',"");asset_info_return_obj['error_message']=(current_error_msg_pexels+" Pexels failed for base.").strip()
        if asset_info_return_obj['error']:
            logger.warning("Base img (DALL-E/Pexels) failed. Using placeholder.");placeholder_prompt_text_val =asset_info_return_obj.get('prompt_used',image_generation_prompt_text);placeholder_path_result=self._create_placeholder_image_content(f"[Base Placeholder]{placeholder_prompt_text_val[:70]}...",filename_for_base_image_output);
            if placeholder_path_result:path_to_input_image_for_runway=placeholder_path_result;asset_info_return_obj={'path':placeholder_path_result,'type':'image','error':False,'prompt_used':placeholder_prompt_text_val}
            else:current_error_msg_ph=asset_info_return_obj.get('error_message',"");asset_info_return_obj['error_message']=(current_error_msg_ph+" Base placeholder failed.").strip()
        if generate_as_video_clip_flag:
            if not path_to_input_image_for_runway:logger.error("RunwayML video: base img failed.");asset_info_return_obj['error']=True;asset_info_return_obj['error_message']=(asset_info_return_obj.get('error_message',"")+" Base img miss, Runway abort.").strip();asset_info_return_obj['type']='none';return asset_info_return_obj
            if self.USE_RUNWAYML:
                runway_generated_video_path=self._generate_video_clip_with_runwayml(motion_prompt_text_for_video,path_to_input_image_for_runway,base_name_current_asset,runway_target_duration_val)
                if runway_generated_video_path and os.path.exists(runway_generated_video_path):asset_info_return_obj={'path':runway_generated_video_path,'type':'video','error':False,'prompt_used':motion_prompt_text_for_video,'base_image_path':path_to_input_image_for_runway}
                else:logger.warning(f"RunwayML video failed for {base_name_current_asset}. Fallback to base img.");asset_info_return_obj['error']=True;asset_info_return_obj['error_message']=(asset_info_return_obj.get('error_message',"Base img ok.")+" RunwayML video fail; use base img.").strip();asset_info_return_obj['path']=path_to_input_image_for_runway;asset_info_return_obj['type']='image';asset_info_return_obj['prompt_used']=image_generation_prompt_text
            else:logger.warning("RunwayML selected but disabled. Use base img.");asset_info_return_obj['error']=True;asset_info_return_obj['error_message']=(asset_info_return_obj.get('error_message',"Base img ok.")+" RunwayML disabled; use base img.").strip();asset_info_return_obj['path']=path_to_input_image_for_runway;asset_info_return_obj['type']='image';asset_info_return_obj['prompt_used']=image_generation_prompt_text
        return asset_info_return_obj

    def generate_narration_audio(self, text_to_narrate, output_filename="narration_overall.mp3"):
        # <<< CORRECTED METHOD with try/except >>>
        if not self.USE_ELEVENLABS or not self.elevenlabs_client_instance or not text_to_narrate:
            logger.info("ElevenLabs conditions not met (service disabled, client not init, or no text). Skipping audio generation.")
            return None
        audio_filepath_narration = os.path.join(self.output_dir, output_filename)
        try: # Main try block for the entire operation
            logger.info(f"Generating ElevenLabs audio (Voice ID: {self.elevenlabs_voice_id}) for text: \"{text_to_narrate[:70]}...\"")
            audio_stream_method_11l = None
            if hasattr(self.elevenlabs_client_instance, 'text_to_speech') and hasattr(self.elevenlabs_client_instance.text_to_speech, 'stream'):
                audio_stream_method_11l = self.elevenlabs_client_instance.text_to_speech.stream; logger.info("Using ElevenLabs SDK method: client.text_to_speech.stream()")
            elif hasattr(self.elevenlabs_client_instance, 'generate_stream'):
                audio_stream_method_11l = self.elevenlabs_client_instance.generate_stream; logger.info("Using ElevenLabs SDK method: client.generate_stream()")
            elif hasattr(self.elevenlabs_client_instance, 'generate'):
                logger.info("Using ElevenLabs SDK method: client.generate() (non-streaming).")
                voice_param_11l = str(self.elevenlabs_voice_id)
                if Voice and self.elevenlabs_voice_settings_obj: voice_param_11l = Voice(voice_id=str(self.elevenlabs_voice_id), settings=self.elevenlabs_voice_settings_obj)
                audio_bytes_data = self.elevenlabs_client_instance.generate(text=text_to_narrate, voice=voice_param_11l, model="eleven_multilingual_v2")
                with open(audio_filepath_narration, "wb") as audio_file_out: audio_file_out.write(audio_bytes_data)
                logger.info(f"ElevenLabs audio (non-streamed) saved successfully to: {audio_filepath_narration}"); return audio_filepath_narration
            else: logger.error("No recognized audio generation method found on the ElevenLabs client instance."); return None

            if audio_stream_method_11l:
                params_for_voice_stream = {"voice_id": str(self.elevenlabs_voice_id)}
                if self.elevenlabs_voice_settings_obj:
                    if hasattr(self.elevenlabs_voice_settings_obj, 'model_dump'): params_for_voice_stream["voice_settings"] = self.elevenlabs_voice_settings_obj.model_dump()
                    elif hasattr(self.elevenlabs_voice_settings_obj, 'dict'): params_for_voice_stream["voice_settings"] = self.elevenlabs_voice_settings_obj.dict()
                    else: params_for_voice_stream["voice_settings"] = self.elevenlabs_voice_settings_obj
                audio_data_iterator_11l = audio_stream_method_11l(text=text_to_narrate, model_id="eleven_multilingual_v2", **params_for_voice_stream)
                with open(audio_filepath_narration, "wb") as audio_file_out_stream:
                    for audio_chunk_data in audio_data_iterator_11l:
                        if audio_chunk_data: audio_file_out_stream.write(audio_chunk_data)
                logger.info(f"ElevenLabs audio (streamed) saved successfully to: {audio_filepath_narration}"); return audio_filepath_narration
        except AttributeError as ae_11l_sdk: logger.error(f"AttributeError with ElevenLabs SDK client: {ae_11l_sdk}. SDK version/methods might differ.", exc_info=True); return None
        except Exception as e_11l_general_audio: logger.error(f"General error during ElevenLabs audio generation: {e_11l_general_audio}", exc_info=True); return None

    def assemble_animatic_from_assets(self, asset_data_list, overall_narration_path=None, output_filename="final_video.mp4", fps=24):
        if not asset_data_list: logger.warning("No assets for animatic."); return None
        processed_moviepy_clips_list = []; narration_audio_clip_mvpy = None; final_video_output_clip = None
        logger.info(f"Assembling from {len(asset_data_list)} assets. Target Frame: {self.video_frame_size}.")

        for i_asset, asset_info_item_loop in enumerate(asset_data_list):
            path_of_asset, type_of_asset, duration_for_scene = asset_info_item_loop.get('path'), asset_info_item_loop.get('type'), asset_info_item_loop.get('duration', 4.5)
            num_of_scene, action_in_key = asset_info_item_loop.get('scene_num', i_asset + 1), asset_info_item_loop.get('key_action', '')
            logger.info(f"S{num_of_scene}: Path='{path_of_asset}', Type='{type_of_asset}', Dur='{duration_for_scene}'s")

            if not (path_of_asset and os.path.exists(path_of_asset)): logger.warning(f"S{num_of_scene}: Not found '{path_of_asset}'. Skip."); continue
            if duration_for_scene <= 0: logger.warning(f"S{num_of_scene}: Invalid duration ({duration_for_scene}s). Skip."); continue
            
            active_scene_clip = None
            try:
                if type_of_asset == 'image':
                    pil_img_original = Image.open(path_of_asset); logger.debug(f"S{num_of_scene} (0-Load): Original. Mode:{pil_img_original.mode}, Size:{pil_img_original.size}"); pil_img_original.save(os.path.join(self.output_dir,f"debug_0_ORIGINAL_S{num_of_scene}.png"))
                    img_rgba_intermediate = pil_img_original.convert('RGBA') if pil_img_original.mode != 'RGBA' else pil_img_original.copy().convert('RGBA'); logger.debug(f"S{num_of_scene} (1-ToRGBA): Mode:{img_rgba_intermediate.mode}, Size:{img_rgba_intermediate.size}"); img_rgba_intermediate.save(os.path.join(self.output_dir,f"debug_1_AS_RGBA_S{num_of_scene}.png"))
                    thumbnailed_img_rgba = img_rgba_intermediate.copy(); resample_filter_pil = Image.Resampling.LANCZOS if hasattr(Image.Resampling,'LANCZOS') else Image.BILINEAR; thumbnailed_img_rgba.thumbnail(self.video_frame_size, resample_filter_pil); logger.debug(f"S{num_of_scene} (2-Thumbnail): Mode:{thumbnailed_img_rgba.mode}, Size:{thumbnailed_img_rgba.size}"); thumbnailed_img_rgba.save(os.path.join(self.output_dir,f"debug_2_THUMBNAIL_RGBA_S{num_of_scene}.png"))
                    canvas_for_compositing_rgba = Image.new('RGBA', self.video_frame_size, (0,0,0,0)); pos_x_paste = (self.video_frame_size[0] - thumbnailed_img_rgba.width) // 2; pos_y_paste = (self.video_frame_size[1] - thumbnailed_img_rgba.height) // 2; canvas_for_compositing_rgba.paste(thumbnailed_img_rgba, (pos_x_paste, pos_y_paste), thumbnailed_img_rgba); logger.debug(f"S{num_of_scene} (3-PasteOnRGBA): Mode:{canvas_for_compositing_rgba.mode}, Size:{canvas_for_compositing_rgba.size}"); canvas_for_compositing_rgba.save(os.path.join(self.output_dir,f"debug_3_COMPOSITED_RGBA_S{num_of_scene}.png"))
                    final_rgb_image_for_pil = Image.new("RGB", self.video_frame_size, (0, 0, 0)); 
                    if canvas_for_compositing_rgba.mode == 'RGBA': final_rgb_image_for_pil.paste(canvas_for_compositing_rgba, mask=canvas_for_compositing_rgba.split()[3])
                    else: final_rgb_image_for_pil.paste(canvas_for_compositing_rgba)
                    logger.debug(f"S{num_of_scene} (4-ToRGB): Final RGB. Mode:{final_rgb_image_for_pil.mode}, Size:{final_rgb_image_for_pil.size}")
                    debug_path_img_pre_numpy = os.path.join(self.output_dir,f"debug_4_PRE_NUMPY_RGB_S{num_of_scene}.png"); final_rgb_image_for_pil.save(debug_path_img_pre_numpy); logger.info(f"CRITICAL DEBUG: Saved PRE_NUMPY_RGB_S{num_of_scene} to {debug_path_img_pre_numpy}")
                    
                    numpy_frame_arr = np.array(final_rgb_image_for_pil, dtype=np.uint8)
                    if not numpy_frame_arr.flags['C_CONTIGUOUS']: numpy_frame_arr = np.ascontiguousarray(numpy_frame_arr, dtype=np.uint8)
                    logger.debug(f"S{num_of_scene} (5-NumPy): Final NumPy. Shape:{numpy_frame_arr.shape}, DType:{numpy_frame_arr.dtype}, Flags:{numpy_frame_arr.flags}")
                    if numpy_frame_arr.size == 0 or numpy_frame_arr.ndim != 3 or numpy_frame_arr.shape[2] != 3: logger.error(f"S{num_of_scene}: Invalid NumPy shape/size ({numpy_frame_arr.shape}). Skipping."); continue
                    
                    base_image_clip_mvpy = ImageClip(numpy_frame_arr, transparent=False, ismask=False).set_duration(duration_for_scene)
                    logger.debug(f"S{num_of_scene} (6-ImageClip): Base ImageClip. Duration: {base_image_clip_mvpy.duration}")

                    debug_path_moviepy_frame = os.path.join(self.output_dir,f"debug_7_MOVIEPY_FRAME_S{num_of_scene}.png")
                    # <<< THIS IS THE CORRECTED TRY-EXCEPT BLOCK >>>
                    try:
                        save_frame_time = min(0.1, base_image_clip_mvpy.duration / 2 if base_image_clip_mvpy.duration > 0 else 0.1)
                        base_image_clip_mvpy.save_frame(debug_path_moviepy_frame, t=save_frame_time) 
                        logger.info(f"CRITICAL DEBUG: Saved frame FROM MOVIEPY ImageClip S{num_of_scene} to {debug_path_moviepy_frame}")
                    except Exception as e_save_mvpy_frame:
                        logger.error(f"DEBUG: Error saving frame FROM MOVIEPY ImageClip S{num_of_scene}: {e_save_mvpy_frame}", exc_info=True)
                    
                    fx_image_clip_mvpy = base_image_clip_mvpy
                    try:
                        scale_end_kb_val = random.uniform(1.03, 1.08)
                        if duration_for_scene > 0: fx_image_clip_mvpy = base_image_clip_mvpy.fx(vfx.resize, lambda t_val: 1 + (scale_end_kb_val - 1) * (t_val / duration_for_scene)).set_position('center'); logger.debug(f"S{num_of_scene} (8-KenBurns): Ken Burns applied.")
                        else: logger.warning(f"S{num_of_scene}: Duration zero, skipping Ken Burns.")
                    except Exception as e_kb_fx_loop: logger.error(f"S{num_of_scene} Ken Burns error: {e_kb_fx_loop}", exc_info=False)
                    active_scene_clip = fx_image_clip_mvpy
                elif type_of_asset == 'video':
                    source_video_clip_obj=None
                    try:
                        logger.debug(f"S{num_of_scene}: Loading VIDEO asset: {path_of_asset}")
                        source_video_clip_obj=VideoFileClip(path_of_asset,target_resolution=(self.video_frame_size[1],self.video_frame_size[0])if self.video_frame_size else None, audio=False)
                        temp_video_clip_obj_loop=source_video_clip_obj
                        if source_video_clip_obj.duration!=duration_for_scene:
                            if source_video_clip_obj.duration>duration_for_scene:temp_video_clip_obj_loop=source_video_clip_obj.subclip(0,duration_for_scene)
                            else:
                                if duration_for_scene/source_video_clip_obj.duration > 1.5 and source_video_clip_obj.duration>0.1:temp_video_clip_obj_loop=source_video_clip_obj.loop(duration=duration_for_scene)
                                else:temp_video_clip_obj_loop=source_video_clip_obj.set_duration(source_video_clip_obj.duration);logger.info(f"S{num_of_scene} Video clip ({source_video_clip_obj.duration:.2f}s) shorter than target ({duration_for_scene:.2f}s).")
                        active_scene_clip=temp_video_clip_obj_loop.set_duration(duration_for_scene)
                        if active_scene_clip.size!=list(self.video_frame_size):active_scene_clip=active_scene_clip.resize(self.video_frame_size)
                        logger.debug(f"S{num_of_scene}: Video asset processed. Final duration: {active_scene_clip.duration:.2f}s")
                    except Exception as e_vid_load_loop:logger.error(f"S{num_of_scene} Video load error '{path_of_asset}':{e_vid_load_loop}",exc_info=True);continue
                    finally:
                        if source_video_clip_obj and source_video_clip_obj is not active_scene_clip and hasattr(source_video_clip_obj,'close'):
                            try: source_video_clip_obj.close()
                            except Exception as e_close_src_vid: logger.warning(f"S{num_of_scene}: Error closing source VideoFileClip: {e_close_src_vid}")
                else: logger.warning(f"S{num_of_scene} Unknown asset type '{type_of_asset}'. Skipping."); continue
                if active_scene_clip and action_in_key:
                    try:
                        dur_text_overlay_val=min(active_scene_clip.duration-0.5,active_scene_clip.duration*0.8)if active_scene_clip.duration>0.5 else (active_scene_clip.duration if active_scene_clip.duration > 0 else 0)
                        start_text_overlay_val=0.25 if active_scene_clip.duration > 0.5 else 0
                        if dur_text_overlay_val > 0:
                            text_clip_for_overlay_obj=TextClip(f"Scene {num_of_scene}\n{action_in_key}",fontsize=self.VIDEO_OVERLAY_FONT_SIZE,color=self.VIDEO_OVERLAY_FONT_COLOR,font=self.active_moviepy_font_name,bg_color='rgba(10,10,20,0.7)',method='caption',align='West',size=(self.video_frame_size[0]*0.9,None),kerning=-1,stroke_color='black',stroke_width=1.5).set_duration(dur_text_overlay_val).set_start(start_text_overlay_val).set_position(('center',0.92),relative=True)
                            active_scene_clip=CompositeVideoClip([active_scene_clip,text_clip_for_overlay_obj],size=self.video_frame_size,use_bgclip=True)
                            logger.debug(f"S{num_of_scene}: Text overlay composited.")
                        else: logger.warning(f"S{num_of_scene}: Text overlay duration zero or negative ({dur_text_overlay_val}). Skipping text overlay.")
                    except Exception as e_txt_comp_loop:logger.error(f"S{num_of_scene} TextClip compositing error:{e_txt_comp_loop}. Proceeding without text for this scene.",exc_info=True)
                if active_scene_clip: processed_moviepy_clips_list.append(active_scene_clip); logger.info(f"S{num_of_scene}: Asset successfully processed. Clip duration: {active_scene_clip.duration:.2f}s. Added to final list.")
            except Exception as e_asset_loop_main_exc: logger.error(f"MAJOR UNHANDLED ERROR processing asset for S{num_of_scene} (Path: {path_of_asset}): {e_asset_loop_main_exc}", exc_info=True)
            finally:
                if active_scene_clip and hasattr(active_scene_clip,'close'):
                    try: active_scene_clip.close()
                    except Exception as e_close_active_err: logger.warning(f"S{num_of_scene}: Error closing active_scene_clip in error handler: {e_close_active_err}")
        
        if not processed_moviepy_clips_list: logger.warning("No MoviePy clips were successfully processed. Aborting animatic assembly before concatenation."); return None
        transition_duration_val=0.75
        try:
            logger.info(f"Concatenating {len(processed_moviepy_clips_list)} processed clips for final animatic.");
            if len(processed_moviepy_clips_list)>1: final_video_output_clip=concatenate_videoclips(processed_moviepy_clips_list, padding=-transition_duration_val if transition_duration_val > 0 else 0, method="compose")
            elif processed_moviepy_clips_list: final_video_output_clip=processed_moviepy_clips_list[0]
            if not final_video_output_clip: logger.error("Concatenation resulted in a None clip. Aborting."); return None
            logger.info(f"Concatenated animatic base duration:{final_video_output_clip.duration:.2f}s")
            if transition_duration_val > 0 and final_video_output_clip.duration > 0:
                if final_video_output_clip.duration > transition_duration_val * 2: final_video_output_clip=final_video_output_clip.fx(vfx.fadein,transition_duration_val).fx(vfx.fadeout,transition_duration_val)
                else: final_video_output_clip=final_video_output_clip.fx(vfx.fadein,min(transition_duration_val,final_video_output_clip.duration/2.0))
                logger.debug("Applied fade in/out effects to final composite clip.")
            if overall_narration_path and os.path.exists(overall_narration_path) and final_video_output_clip.duration > 0:
                try: narration_audio_clip_mvpy=AudioFileClip(overall_narration_path); logger.info(f"Adding overall narration. Video duration: {final_video_output_clip.duration:.2f}s, Narration duration: {narration_audio_clip_mvpy.duration:.2f}s"); final_video_output_clip=final_video_output_clip.set_audio(narration_audio_clip_mvpy); logger.info("Overall narration successfully added to animatic.")
                except Exception as e_narr_add_final:logger.error(f"Error adding overall narration to animatic:{e_narr_add_final}",exc_info=True)
            elif final_video_output_clip.duration <= 0: logger.warning("Animatic has zero or negative duration before adding audio. Audio will not be added.")
            if final_video_output_clip and final_video_output_clip.duration > 0:
                final_output_path_str=os.path.join(self.output_dir,output_filename); logger.info(f"Writing final animatic video to: {final_output_path_str} (Target Duration: {final_video_output_clip.duration:.2f}s)")
                num_threads = os.cpu_count(); num_threads = num_threads if isinstance(num_threads, int) and num_threads >= 1 else 2
                final_video_output_clip.write_videofile(final_output_path_str, fps=fps, codec='libx264', preset='medium', audio_codec='aac', temp_audiofile=os.path.join(self.output_dir,f'temp-audio-{os.urandom(4).hex()}.m4a'), remove_temp=True, threads=num_threads, logger='bar', bitrate="5000k", ffmpeg_params=["-pix_fmt", "yuv420p"])
                logger.info(f"Animatic video created successfully: {final_output_path_str}"); return final_output_path_str
            else: logger.error("Final animatic clip is invalid or has zero duration. Cannot write video file."); return None
        except Exception as e_vid_write_final_op: logger.error(f"Error during final animatic video file writing or composition stage: {e_vid_write_final_op}", exc_info=True); return None
        finally:
            logger.debug("Closing all MoviePy clips in `assemble_animatic_from_assets` main finally block.")
            all_clips_for_closure = processed_moviepy_clips_list[:]
            if narration_audio_clip_mvpy and hasattr(narration_audio_clip_mvpy, 'close'): all_clips_for_closure.append(narration_audio_clip_mvpy)
            if final_video_output_clip and hasattr(final_video_output_clip, 'close'): all_clips_for_closure.append(final_video_output_clip)
            for clip_to_close_item_final in all_clips_for_closure:
                if clip_to_close_item_final and hasattr(clip_to_close_item_final, 'close'):
                    try: clip_to_close_item_final.close()
                    except Exception as e_final_clip_close_op: logger.warning(f"Ignoring error while closing a MoviePy clip ({type(clip_to_close_item_final).__name__}): {e_final_clip_close_op}")