diodiogod-TTS-Audio-Suite/utils/text/character_parser_backup.py

"""
Character Parser for ChatterBox Voice - Universal Text Processing
Handles character tag parsing for both F5TTS and ChatterBox TTS nodes
"""

import re
from dataclasses import dataclass
from typing import List, Tuple, Dict, Optional, Union
from pathlib import Path
from utils.models.language_mapper import resolve_language_alias, LANGUAGE_ALIASES


@dataclass
class CharacterSegment:
    """Represents a single text segment with character assignment and language"""
    character: str
    text: str
    start_pos: int
    end_pos: int
    language: Optional[str] = None
    original_character: Optional[str] = None  # Original character before alias resolution
    explicit_language: bool = False  # True if language was explicitly specified in tag (e.g., [German:Bob])
    
    def __str__(self) -> str:
        lang_info = f", lang='{self.language}'" if self.language else ""
        orig_info = f", orig='{self.original_character}'" if self.original_character and self.original_character != self.character else ""
        return f"CharacterSegment(character='{self.character}'{orig_info}{lang_info}, text='{self.text[:50]}...', pos={self.start_pos}-{self.end_pos})"


class CharacterParser:
    """
    Universal character parsing system for both F5TTS and ChatterBox TTS.
    
    Features:
    - Parse [CharacterName] and [language:CharacterName] tags from text
    - Split text into character-specific segments with language awareness
    - Robust fallback system for missing characters
    - Support for both single text and SRT subtitle processing
    - Compatible with voice folder structure
    - Language-aware character switching
    """
    
    # Regex pattern for character tags: [CharacterName] or [language:CharacterName] 
    # Excludes: pause tags, standalone Italian tags [it]/[italian] (but allows [it:]/[italian:])
    CHARACTER_TAG_PATTERN = re.compile(r'\[(?!(?:pause|wait|stop|Pause|Wait|Stop|PAUSE|WAIT|STOP):)(?!(?:it|IT|italian|Italian)\])([^\]]+)\]')
    
    # Regex to parse language:character format (supports flexible language names)
    LANGUAGE_CHARACTER_PATTERN = re.compile(r'^([a-zA-Z0-9\-_À-ÿ\s]+):(.*)$')
    
    def __init__(self, default_character: str = "narrator", default_language: Optional[str] = None):
        """
        Initialize character parser.
        
        Args:
            default_character: Default character name for untagged text
            default_language: Default language for characters without explicit language
        """
        self.default_character = default_character
        self.default_language = default_language or "en"
        self.available_characters = set()
        self.character_fallbacks = {}
        self.character_language_defaults = {}
        
        # Cache for character language resolution to prevent duplicate logging
        self._character_language_cache = {}
        self._logged_characters = set()
        self._logged_character_warnings = set()
        
        # Note: Using centralized language alias system from utils.models.language_mapper
    
    def resolve_language_alias(self, language_input: str) -> str:
        """
        Resolve language alias to canonical language code using centralized system.
        
        Args:
            language_input: User input language (e.g., "German", "brasil", "pt-BR")
            
        Returns:
            Canonical language code (e.g., "de", "pt-br")
        """
        return resolve_language_alias(language_input)
    
    def set_available_characters(self, characters: List[str]):
        """
        Set list of available character voices.
        
        Args:
            characters: List of character names that have voice references
        """
        self.available_characters = set(char.lower() for char in characters)
    
    def add_character_fallback(self, character: str, fallback: str):
        """
        Add a fallback mapping for a character.
        
        Args:
            character: Character name that might not exist
            fallback: Character name to use as fallback
        """
        self.character_fallbacks[character.lower()] = fallback.lower()
    
    def set_character_language_default(self, character: str, language: str):
        """
        Set default language for a character.
        
        Args:
            character: Character name
            language: Default language code (e.g., 'en', 'de', 'fr')
        """
        self.character_language_defaults[character.lower()] = language.lower()
    
    def parse_language_character_tag(self, tag_content: str) -> Tuple[Optional[str], str]:
        """
        Parse character tag content to extract language and character.
        
        Args:
            tag_content: Content inside character brackets (e.g., "Alice" or "de:Alice")
            
        Returns:
            Tuple of (language, character_name) where language can be None
        """
        # Check if it's in language:character format
        match = self.LANGUAGE_CHARACTER_PATTERN.match(tag_content.strip())
        if match:
            raw_language = match.group(1)
            character = match.group(2).strip()
            # Resolve language alias to canonical form
            language = self.resolve_language_alias(raw_language)
            # If character is empty (e.g., [fr:]), default to narrator
            if not character:
                character = self.default_character
            return language, character
        else:
            # Just a character name, no explicit language
            return None, tag_content.strip()
    
    def resolve_character_language(self, character: str, explicit_language: Optional[str] = None) -> str:
        """
        Resolve the language to use for a character with caching to prevent log spam.
        
        Priority:
        1. Explicitly provided language (from [lang:character] tag)
        2. Character's default language (from alias system)
        3. Global default language
        
        Args:
            character: Character name
            explicit_language: Language explicitly specified in tag
            
        Returns:
            Language code to use (normalized, no local: prefix)
        """
        if explicit_language:
            # Normalize explicit language immediately
            if explicit_language.startswith("local:"):
                explicit_language = explicit_language[6:]
            return explicit_language
        
        character_lower = character.lower()
        
        # Check cache first to avoid repeated lookups and logging
        cache_key = character_lower
        if cache_key in self._character_language_cache:
            return self._character_language_cache[cache_key]
        
        resolved_language = None
        
        # Priority 1: Character language defaults (internal cache)
        if character_lower in self.character_language_defaults:
            resolved_language = self.character_language_defaults[character_lower]
            # Normalize alias language
            if resolved_language and resolved_language.startswith("local:"):
                resolved_language = resolved_language[6:]
            # Only log once per character
            if character_lower not in self._logged_characters:
                print(f"🎭 Character '{character}' auto-switching to 🚨 alias default language '{resolved_language}'")
                self._logged_characters.add(character_lower)
        
        # Priority 2: Check voice discovery system for language defaults
        if not resolved_language:
            try:
                from utils.voice.discovery import voice_discovery
                alias_language = voice_discovery.get_character_default_language(character_lower)
                if alias_language:
                    resolved_language = alias_language
                    # Normalize alias language from voice discovery
                    if resolved_language and resolved_language.startswith("local:"):
                        resolved_language = resolved_language[6:]
                    # Only log once per character
                    if character_lower not in self._logged_characters:
                        print(f"🎭 Character '{character}' auto-switching to 🚨 alias default language '{resolved_language}'")
                        self._logged_characters.add(character_lower)
                # Remove spam: don't log "has no language default" for every character
            except Exception:
                pass  # Silently handle voice discovery errors
        
        # Priority 3: Fall back to global default
        if not resolved_language:
            resolved_language = self.default_language
        
        # Normalize local: prefix for consistency
        if resolved_language and resolved_language.startswith("local:"):
            resolved_language = resolved_language[6:]
        
        # Cache the result
        self._character_language_cache[cache_key] = resolved_language
        return resolved_language
    
    def reset_session_cache(self):
        """Reset caches for a new parsing session to allow fresh logging."""
        self._character_language_cache.clear()
        self._logged_characters.clear()
        self._logged_character_warnings.clear()
    
    def get_character_language_summary(self) -> str:
        """
        Get a consolidated summary of character language mappings for logging.
        
        Returns:
            Formatted summary string of character→language mappings
        """
        if not self._character_language_cache:
            return ""
        
        # Group characters by language
        lang_groups = {}
        for char, lang in self._character_language_cache.items():
            if lang not in lang_groups:
                lang_groups[lang] = []
            lang_groups[lang].append(char)
        
        # Format as: Alice(de), Bob(fr→en fallback), Others(en)
        summary_parts = []
        for lang, chars in sorted(lang_groups.items()):
            if len(chars) == 1:
                summary_parts.append(f"{chars[0]}({lang})")
            else:
                summary_parts.append(f"{', '.join(chars)}({lang})")
        
        return ', '.join(summary_parts)
    
    def set_engine_aware_default_language(self, model_or_language: str, engine_type: str):
        """
        Set default language based on engine model or language code.
        
        Args:
            model_or_language: Either a model name (F5-TTS) or language code (ChatterBox)
            engine_type: Engine type ("f5tts" or "chatterbox")
        """
        # ChatterBox passes language codes directly, F5-TTS passes model names
        if engine_type == "chatterbox":
            # ChatterBox gives us language names (with possible local: prefix)
            # Need to normalize to language codes
            normalized_language = self._normalize_chatterbox_language(model_or_language)
            self.default_language = normalized_language
            # print(f"🔧 Character Parser: Default language set to '{normalized_language}' for ChatterBox (from '{model_or_language}')")
        else:
            # F5-TTS gives us model names, need to infer language
            inferred_language = self._infer_language_from_engine_model(model_or_language, engine_type)
            if inferred_language:
                self.default_language = inferred_language
                # print(f"🔧 Character Parser: Default language set to '{inferred_language}' based on F5-TTS model '{model_or_language}'")
    
    def _infer_language_from_engine_model(self, model_name: str, engine_type: str) -> Optional[str]:
        """
        Infer language code from engine model name.
        
        Args:
            model_name: Model name (e.g., "F5-PT-BR", "F5TTS_Base")
            engine_type: Engine type ("f5tts" or "chatterbox")
            
        Returns:
            Inferred language code or None if can't infer
        """
        try:
            # Use the existing language mapper system - much cleaner and flexible!
            from utils.models.language_mapper import get_language_mapper
            
            mapper = get_language_mapper(engine_type)
            mappings = mapper.get_all_mappings().get(engine_type, {})
            
            # Normalize model name for reverse lookup (remove local: prefix)
            normalized_model = model_name
            if normalized_model.startswith("local:"):
                normalized_model = normalized_model[6:]
            
            # Reverse lookup: find language code that maps to this model
            for lang_code, mapped_model in mappings.items():
                if mapped_model == normalized_model:
                    return lang_code
            
            # Fallback for base models that aren't in specific language mappings
            if engine_type == "f5tts" and any(x in normalized_model.lower() for x in ['f5tts_base', 'f5tts_v1_base', 'e2tts_base']):
                return 'en'
            elif engine_type == "chatterbox" and 'english' in normalized_model.lower():
                return 'en'
                
        except ImportError:
            # Fallback if language mapper not available - shouldn't happen but just in case
            pass
        
        return None  # Can't infer language
    
    def _normalize_chatterbox_language(self, language_input: str) -> str:
        """
        Normalize ChatterBox language input to canonical language code.
        
        Args:
            language_input: ChatterBox language (e.g., "German", "local:German", "de")
            
        Returns:
            Normalized language code (local: prefix removed for consistency)
        """
        # Remove local: prefix for consistency - model loading will still use local models
        if language_input.startswith("local:"):
            language_input = language_input[6:]
        
        # Map ChatterBox model names to language codes
        chatterbox_language_map = {
            # Legacy ChatterBox models
            "english": "en",
            "german": "de", 
            "norwegian": "no",
            "french": "fr",
            "italian": "it", 
            "russian": "ru",
            "korean": "ko",
            "japanese": "ja",
            "armenian": "hy",
            "georgian": "ka",
            
            # ChatterBox Official 23-Lang (single model name resolves to default language)
            "chatterbox official 23-lang": None,  # Will use actual language selection from UI
        }
        
        # Check if it's a ChatterBox model name
        normalized = language_input.lower()
        if normalized in chatterbox_language_map:
            mapped = chatterbox_language_map[normalized]
            if mapped is not None:
                return mapped
        
        # For ChatterBox Official 23-Lang or unknown languages, resolve using language aliases
        # This handles language names like "Arabic", "Turkish", "Chinese", etc.
        resolved = self.resolve_language_alias(language_input)
        return resolved
    
    def normalize_character_name(self, character_name: str, skip_narrator_alias: bool = False) -> str:
        """
        Normalize character name and apply alias resolution and fallback if needed.
        
        Args:
            character_name: Raw character name from tag
            skip_narrator_alias: If True, skip alias resolution for "narrator" character
            
        Returns:
            Normalized character name or fallback
        """
        # Clean and normalize
        normalized = character_name.strip().lower()
        
        # Remove common punctuation from character names
        normalized = re.sub(r'[：:,，]', '', normalized)
        
        # First, try to resolve through alias system
        # Skip alias resolution for "narrator" when it comes from language-only tags
        # This preserves user's narrator voice priority (opt_narrator > dropdown > character map)
        if not (skip_narrator_alias and normalized == "narrator"):
            try:
                from utils.voice.discovery import voice_discovery
                resolved = voice_discovery.resolve_character_alias(normalized)
                if resolved != normalized:
                    # print(f"🗂️ Character Parser: '{character_name}' → '{resolved}' (alias)")
                    normalized = resolved
            except Exception as e:
                # If alias resolution fails, continue with original name
                pass
        
        # Check if character is available
        if normalized in self.available_characters:
            return normalized
        
        # Check fallback mapping
        if normalized in self.character_fallbacks:
            fallback = self.character_fallbacks[normalized]
            print(f"🔄 Character Parser: '{character_name}' → '{fallback}' (fallback)")
            return fallback
        
        # Default fallback - only log once per character per session
        if character_name not in self._logged_character_warnings:
            print(f"⚠️ Character Parser: Character '{character_name}' not found, using '{self.default_character}'")
            self._logged_character_warnings.add(character_name)
        return self.default_character
    
    def parse_text_segments(self, text: str) -> List[CharacterSegment]:
        """
        Parse text into character-specific segments with proper line-by-line processing.
        
        Args:
            text: Input text with [Character] tags
            
        Returns:
            List of CharacterSegment objects
        """
        segments = []
        
        # Split text by lines and process each line completely independently
        lines = text.split('\n')
        global_pos = 0
        
        for line in lines:
            line_start_pos = global_pos
            original_line = line
            line = line.strip()
            
            if not line:
                global_pos += len(original_line) + 1  # Account for empty line + newline
                continue
            
            # Each line is processed independently - no character state carries over
            line_segments = self._parse_single_line(line, line_start_pos)
            segments.extend(line_segments)
            
            global_pos += len(original_line) + 1  # +1 for newline
        
        # If no segments were created, treat entire text as default character
        if not segments and text.strip():
            segments.append(CharacterSegment(
                character=self.default_character,
                text=text.strip(),
                start_pos=0,
                end_pos=len(text),
                language=self.resolve_character_language(self.default_character),
                original_character=self.default_character,
                explicit_language=False
            ))
        
        return segments
    
    def _parse_single_line(self, line: str, line_start_pos: int) -> List[CharacterSegment]:
        """
        Parse a single line for character tags, treating it completely independently.
        
        Args:
            line: Single line of text (no newlines)
            line_start_pos: Starting position of this line in the original text
            
        Returns:
            List of CharacterSegment objects for this line only
        """
        segments = []
        current_pos = 0
        current_character = self.default_character
        current_language = self.default_language
        
        # IMPORTANT: Each line starts fresh with narrator as default
        # If the line doesn't start with a character tag, everything is narrator
        
        # Check for manual "Speaker N:" format before processing character tags
        speaker_match = self._parse_speaker_format_line(line)
        if speaker_match:
            speaker_name, speaker_text = speaker_match
            if speaker_text.strip():
                segments.append(CharacterSegment(
                    character=speaker_name,  # Use "speaker 1", "speaker 2", etc.
                    text=speaker_text.strip(),
                    start_pos=line_start_pos,
                    end_pos=line_start_pos + len(line),
                    language=self.resolve_character_language(speaker_name),
                    original_character=speaker_name,
                    explicit_language=False
                ))
            return segments
        
        # Quick check: if line doesn't contain any character tags, it's all narrator
        if not self.CHARACTER_TAG_PATTERN.search(line):
            if line.strip():
                segments.append(CharacterSegment(
                    character=self.default_character,
                    text=line.strip(),
                    start_pos=line_start_pos,
                    end_pos=line_start_pos + len(line),
                    language=self.resolve_character_language(self.default_character),
                    original_character=self.default_character,
                    explicit_language=False
                ))
            return segments
        
        # Find all character tags in this line
        for match in self.CHARACTER_TAG_PATTERN.finditer(line):
            # Add text before this tag (if any) with current character (narrator)
            before_tag = line[current_pos:match.start()].strip()
            if before_tag:
                segments.append(CharacterSegment(
                    character=current_character,
                    text=before_tag,
                    start_pos=line_start_pos + current_pos,
                    end_pos=line_start_pos + match.start(),
                    language=current_language,
                    original_character=current_character,  # Before this tag, it's already resolved
                    explicit_language=False  # Text before tags doesn't have explicit language
                ))
            
            # Parse language and character from the tag
            raw_tag_content = match.group(1)
            explicit_language, raw_character = self.parse_language_character_tag(raw_tag_content)
            
            # Update current character for text after this tag
            # IMPORTANT: Resolve language using original alias name before character normalization
            current_language = self.resolve_character_language(raw_character, explicit_language)
            original_character = raw_character  # Store original before normalization
            current_explicit_language = explicit_language is not None  # Track if language was explicit
            
            # Detect language-only tags: if the original tag had empty character part and raw_character
            # was defaulted to narrator, skip alias resolution to preserve narrator voice priority
            is_language_only_tag = (raw_character == self.default_character and 
                                   ':' in raw_tag_content and 
                                   raw_tag_content.split(':', 1)[1].strip() == '')
            
            current_character = self.normalize_character_name(raw_character, skip_narrator_alias=is_language_only_tag)
            current_pos = match.end()
        
        # Add remaining text after last tag (or entire line if no tags)
        remaining_text = line[current_pos:].strip()
        if remaining_text:
            segments.append(CharacterSegment(
                character=current_character,
                text=remaining_text,
                start_pos=line_start_pos + current_pos,
                end_pos=line_start_pos + len(line),
                language=current_language,
                original_character=original_character,
                explicit_language=current_explicit_language if 'current_explicit_language' in locals() else False
            ))
        elif not segments and line.strip():
            # Line with only tags and no text after - still need a segment for the line
            # This handles edge cases like a line that is just "[character]"
            segments.append(CharacterSegment(
                character=current_character,
                text="",
                start_pos=line_start_pos,
                end_pos=line_start_pos + len(line),
                language=current_language,
                original_character=original_character if 'original_character' in locals() else current_character,
                explicit_language=current_explicit_language if 'current_explicit_language' in locals() else False
            ))
        
        return segments
    
    def _parse_speaker_format_line(self, line: str) -> Optional[Tuple[str, str]]:
        """
        Parse a line for manual "Speaker N:" format.
        
        Args:
            line: Single line to check
            
        Returns:
            Tuple of (speaker_name, text) if found, None otherwise
        """
        import re
        # Match "Speaker N: text" (case insensitive)
        match = re.match(r'^(speaker\s*\d+)\s*:\s*(.*)$', line.strip(), re.IGNORECASE)
        if match:
            speaker_name = match.group(1).lower().strip()  # Normalize to "speaker 1", "speaker 2", etc.
            speaker_text = match.group(2)
            # Normalize speaker name format
            speaker_name = re.sub(r'\s+', ' ', speaker_name)  # "speaker  1" -> "speaker 1"
            return speaker_name, speaker_text
        return None
    
    def parse_character_mapping(self, text: str) -> Dict[str, List[str]]:
        """
        Parse text and return character-to-text mapping.
        
        Args:
            text: Input text with [Character] tags
            
        Returns:
            Dictionary mapping character names to list of text segments
        """
        segments = self.parse_text_segments(text)
        character_mapping = {}
        
        for segment in segments:
            if segment.character not in character_mapping:
                character_mapping[segment.character] = []
            character_mapping[segment.character].append(segment.text)
        
        return character_mapping
    
    def get_character_list(self, text: str) -> List[str]:
        """
        Get list of unique characters used in text.
        
        Args:
            text: Input text with [Character] tags
            
        Returns:
            List of unique character names used
        """
        segments = self.parse_text_segments(text)
        return list(set(segment.character for segment in segments))
    
    def remove_character_tags(self, text: str) -> str:
        """
        Remove all character tags from text, leaving only the speech content.
        
        Args:
            text: Input text with [Character] tags
            
        Returns:
            Text with character tags removed
        """
        return self.CHARACTER_TAG_PATTERN.sub('', text).strip()
    
    def convert_to_language_hints_for_higgs(self, text: str) -> str:
        """
        Convert character tags with language prefixes to language hints for Higgs Audio 2.
        
        Converts [En:Alice] Hello there -> [English] Hello there
        This preserves language context for the smart Higgs model while removing character switching.
        
        Args:
            text: Input text with [language:character] tags
            
        Returns:
            Text with language hints for Higgs Audio 2
        """
        def replace_tag(match):
            tag_content = match.group(1)
            
            # Parse language:character format
            lang_match = self.LANGUAGE_CHARACTER_PATTERN.match(tag_content.strip())
            if lang_match:
                raw_language = lang_match.group(1).strip()
                # Resolve to canonical form first, then get display name
                canonical_lang = self.resolve_language_alias(raw_language)
                
                # Convert canonical codes to display names using existing alias system
                # Find a human-readable alias that maps to this canonical code
                display_name = None
                for alias, canonical in LANGUAGE_ALIASES.items():
                    if (canonical == canonical_lang and 
                        alias.isalpha() and 
                        len(alias) > 2 and  # Skip short codes like 'en', 'de'
                        alias.islower()):   # Skip uppercase variations
                        display_name = alias.title()
                        break
                
                # Fallback to canonical code if no readable alias found
                if not display_name:
                    display_name = canonical_lang.upper()
                
                return f'[{display_name}]'
            else:
                # Not a language:character tag, remove entirely
                return ''
        
        # Apply conversion
        converted_text = self.CHARACTER_TAG_PATTERN.sub(replace_tag, text)
        
        # Clean up any double spaces
        converted_text = ' '.join(converted_text.split())
        
        return converted_text
    
    def get_language_display_name(self, language_code: str) -> str:
        """
        Get readable display name for a language code using existing alias system.
        
        Args:
            language_code: Language code (e.g., 'en', 'de', 'pt-br')
            
        Returns:
            Readable language name (e.g., 'English', 'German', 'Portuguese')
        """
        # Resolve to canonical form first
        canonical_lang = self.resolve_language_alias(language_code)
        
        # Preferred display names for better readability
        preferred_names = {
            'pt-br': 'Portuguese',
            'pt-pt': 'Portuguese', 
            'zh-cn': 'Chinese',
            'zh-tw': 'Chinese'
        }
        
        if canonical_lang in preferred_names:
            return preferred_names[canonical_lang]
        
        # Find a human-readable alias that maps to this canonical code
        # Prefer explicit common language names first
        preferred_aliases = ['english', 'german', 'french', 'spanish', 'italian', 'norwegian', 'chinese', 'japanese', 'russian', 'portuguese', 'dutch', 'korean']
        
        for preferred in preferred_aliases:
            if preferred in LANGUAGE_ALIASES and LANGUAGE_ALIASES[preferred] == canonical_lang:
                return preferred.title()
        
        # Fallback: find any readable alias (avoid short codes and abbreviations)
        best_alias = None
        for alias, canonical in LANGUAGE_ALIASES.items():
            if (canonical == canonical_lang and 
                alias.isalpha() and 
                len(alias) >= 4 and  # Skip short codes like 'en', 'de', 'usa', 'eng'
                not alias.isupper()):  # Skip uppercase abbreviations
                if not best_alias or len(alias) > len(best_alias):  # Prefer longer names
                    best_alias = alias
        
        if best_alias:
            return best_alias.title()
        
        # Fallback to canonical code if no readable alias found
        return canonical_lang.upper()
    
    def split_by_character(self, text: str, include_language: bool = False) -> Union[List[Tuple[str, str]], List[Tuple[str, str, str]]]:
        """
        Split text by character, returning (character, text, language) tuples.
        This is the main method used by TTS nodes.
        
        Args:
            text: Input text with [Character] tags
            include_language: If True, returns (character, text, language) tuples
            
        Returns:
            List of (character_name, text_content, language) tuples if include_language=True
            List of (character_name, text_content) tuples if include_language=False (backward compatibility)
        """
        # print(f"🔍 Character Parser DEBUG: Input text: {repr(text)}")
        segments = self.parse_text_segments(text)
        
        if include_language:
            result = [(segment.character, segment.text, segment.language) for segment in segments]
        else:
            # Backward compatibility: return old tuple format
            result = [(segment.character, segment.text) for segment in segments]
        
        # print(f"🔍 Character Parser DEBUG: Parsed segments: {result}")
        return result
    
    def split_by_character_with_language(self, text: str) -> List[Tuple[str, str, str]]:
        """
        Split text by character, returning (character, text, language) tuples.
        Convenience method that always includes language information.
        
        Args:
            text: Input text with [Character] or [language:Character] tags
            
        Returns:
            List of (character_name, text_content, language_code) tuples
        """
        segments = self.parse_text_segments(text)
        return [(segment.character, segment.text, segment.language) for segment in segments]
    
    def split_by_character_with_language_and_explicit_flag(self, text: str) -> List[Tuple[str, str, str, bool]]:
        """
        Split text by character, returning (character, text, language, explicit_language) tuples.
        Extended method that includes explicit language flag for Italian prefix handling.
        
        Args:
            text: Input text with [Character] or [language:Character] tags
            
        Returns:
            List of (character_name, text_content, language_code, explicit_language) tuples
        """
        segments = self.parse_text_segments(text)
        
        # Apply Italian prefix directly to segments before returning
        processed_segments = []
        for segment in segments:
            processed_text = self.apply_italian_prefix_if_needed(
                segment.text, segment.character, segment.language, segment.explicit_language
            )
            processed_segments.append((segment.character, processed_text, segment.language, segment.explicit_language))
        
        return processed_segments
    
    def apply_italian_prefix_if_needed(self, text: str, character: str, language: str, explicit_language: bool) -> str:
        """
        Apply [it] prefix to text if Italian language is detected.
        
        The Italian ChatterBox model requires [it] prefix for Italian text but only when:
        - User uses [it:Alice] or [italian:Bob] syntax (explicit_language=True with language='it')
        - User uses [it:] or [italian:] language switching (explicit_language=True with language='it')
        - Character is mapped as Italian in alias system (language='it' from character defaults)
        
        NOT when just using Italian model globally (it's bilingual Italian/English).
        
        Args:
            text: Text content to potentially prefix (should be clean text without character tags)
            character: Character name
            language: Resolved language code
            explicit_language: Whether language was explicitly specified in tag
            
        Returns:
            Text with [it] prefix added if Italian requirements are met
        """
        # Only apply Italian prefix if language is Italian
        if language != 'it':
            return text
        
        # Apply prefix if:
        # 1. Language was explicitly set via [it:Alice] or [italian:] syntax
        # 2. Character has Italian as default language from alias system (not explicit but character-mapped)
        should_apply_prefix = (
            explicit_language or  # User explicitly used [it:] or [italian:] syntax
            (not explicit_language and language == 'it')  # Character mapped to Italian via alias system
        )
        
        if should_apply_prefix:
            # Avoid double-prefixing - check if [it] is already at the start
            if not text.strip().startswith('[it]'):
                return f"[it] {text.strip()}"
        
        return text
    
    def validate_character_tags(self, text: str) -> Tuple[bool, List[str]]:
        """
        Validate character tags in text and return any issues.
        
        Args:
            text: Input text with [Character] tags
            
        Returns:
            Tuple of (is_valid, list_of_issues)
        """
        issues = []
        
        # Find all character tags
        tags = self.CHARACTER_TAG_PATTERN.findall(text)
        
        # Check for empty tags
        empty_tags = [tag for tag in tags if not tag.strip()]
        if empty_tags:
            issues.append(f"Found {len(empty_tags)} empty character tag(s)")
        
        # Check for unmatched brackets
        open_brackets = text.count('[')
        close_brackets = text.count(']')
        if open_brackets != close_brackets:
            issues.append(f"Unmatched brackets: {open_brackets} '[' vs {close_brackets} ']'")
        
        # Check for characters not in available list (if set)
        if self.available_characters:
            unknown_chars = []
            for tag in tags:
                normalized = self.normalize_character_name(tag)
                if normalized == self.default_character and tag.strip().lower() != self.default_character:
                    unknown_chars.append(tag)
            
            if unknown_chars:
                issues.append(f"Unknown characters (will use fallback): {', '.join(unknown_chars)}")
        
        return len(issues) == 0, issues
    
    def get_statistics(self, text: str) -> Dict[str, any]:
        """
        Get statistics about character usage in text.
        
        Args:
            text: Input text with [Character] tags
            
        Returns:
            Dictionary with statistics
        """
        segments = self.parse_text_segments(text)
        
        character_counts = {}
        character_lengths = {}
        
        for segment in segments:
            char = segment.character
            character_counts[char] = character_counts.get(char, 0) + 1
            character_lengths[char] = character_lengths.get(char, 0) + len(segment.text)
        
        total_chars = sum(character_counts.values())
        total_length = sum(character_lengths.values())
        
        return {
            "total_segments": len(segments),
            "unique_characters": len(character_counts),
            "character_counts": character_counts,
            "character_lengths": character_lengths,
            "total_character_switches": total_chars - 1,
            "total_text_length": total_length,
            "average_segment_length": total_length / len(segments) if segments else 0
        }


# Global instance for use across nodes
character_parser = CharacterParser()


def parse_character_text(text: str, available_characters: Optional[List[str]] = None) -> List[Tuple[str, str]]:
    """
    Convenience function to parse character text.
    
    Args:
        text: Input text with [Character] tags
        available_characters: Optional list of available character voices
        
    Returns:
        List of (character_name, text_content) tuples
    """
    if available_characters:
        character_parser.set_available_characters(available_characters)
    else:
        # Clear any previous available_characters to allow auto-discovery
        character_parser.available_characters = set()
        # Auto-discover characters if not provided
        try:
            from utils.voice.discovery import get_available_characters
            auto_chars = get_available_characters()
            if auto_chars:
                character_parser.set_available_characters(list(auto_chars))
        except Exception as e:
            print(f"⚠️ Character Parser: Auto-discovery failed: {e}")
    
    return character_parser.split_by_character(text)


def validate_character_text(text: str) -> Tuple[bool, List[str]]:
    """
    Convenience function to validate character text.
    
    Args:
        text: Input text with [Character] tags
        
    Returns:
        Tuple of (is_valid, list_of_issues)
    """
    return character_parser.validate_character_tags(text)