clicue 0.1.2__tar.gz

clicue-0.1.2/.gitignore

@@ -0,0 +1,15 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Models
+model/
+model-full/
+model*/

clicue-0.1.2/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: clicue
+Version: 0.1.2
+Summary: Add your description here
+Requires-Python: >=3.12
+Requires-Dist: rapidfuzz
+Requires-Dist: rich
+Requires-Dist: sounddevice
+Requires-Dist: vosk

clicue-0.1.2/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "clicue"
+version = "0.1.2"
+
+
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["rapidfuzz", "vosk", "sounddevice", "rich"]
+
+[project.scripts]
+clicue = "clicue.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/clicue", "README.md", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clicue"]
+

clicue-0.1.2/src/clicue/aligner.py

@@ -0,0 +1,73 @@
+import time
+import sys
+from rapidfuzz import fuzz
+
+class Aligner:
+    def __init__(
+        self,
+        script_words: list[str],
+        max_lookahead: int = 20,
+        threshold: float = 70.0,
+        locality_penalty: float = 1.5,
+        window_size: int = None,
+        perf_log: bool = False
+    ):
+        self.script_words = script_words
+        self.lower_words = [w.lower() for w in script_words]
+        self.current_index = 0
+        self.max_lookahead = window_size if window_size is not None else max_lookahead
+        self.threshold = threshold
+        self.locality_penalty = locality_penalty
+        self.perf_log = perf_log
+        self.call_count = 0
+        self.total_time_ms = 0.0
+
+    def advance(self, stt_text: str) -> int:
+        if self.current_index >= len(self.script_words):
+            return self.current_index
+
+        start_time = time.perf_counter()
+
+        stt_words = stt_text.lower().split()
+        if not stt_words:
+            return self.current_index
+
+        clean_stt_text = " ".join(stt_words)
+        match_len = len(stt_words)
+
+        # Restrict lookahead based on STT utterance length
+        effective_lookahead = min(self.max_lookahead, max(6, match_len * 3))
+        end_index = min(self.current_index + effective_lookahead, len(self.script_words))
+
+        best_score = -100.0
+        best_next_idx = self.current_index
+        best_ratio = 0.0
+
+        for i in range(self.current_index, end_index):
+            # Form phrase using pre-lowercased words to eliminate string allocation overhead
+            script_phrase = " ".join(self.lower_words[i:i + match_len])
+            
+            ratio = fuzz.ratio(clean_stt_text, script_phrase)
+
+            # Apply locality penalty for jumping forward
+            distance = i - self.current_index
+            penalized_score = ratio - (distance * self.locality_penalty)
+
+            if penalized_score > best_score:
+                best_score = penalized_score
+                best_ratio = ratio
+                best_next_idx = i + match_len
+
+        # Check threshold
+        if best_ratio >= self.threshold or best_score >= (self.threshold - 10.0):
+            self.current_index = min(best_next_idx, len(self.script_words))
+
+        elapsed_ms = (time.perf_counter() - start_time) * 1000.0
+        self.call_count += 1
+        self.total_time_ms += elapsed_ms
+
+        if self.perf_log and self.call_count % 10 == 0:
+            avg_ms = self.total_time_ms / self.call_count
+            print(f"[PERF] Align call #{self.call_count}: {elapsed_ms:.2f}ms (avg: {avg_ms:.2f}ms) | STT: '{clean_stt_text}' -> Index {self.current_index}", file=sys.stderr)
+
+        return self.current_index

clicue-0.1.2/src/clicue/config.py

@@ -0,0 +1,56 @@
+import os
+import sys
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+DEFAULT_CONFIG = {
+    "scroller": {
+        "window_size": 38,
+        "past_size": 9,
+    },
+    "aligner": {
+        "max_lookahead": 20,
+        "threshold": 70.0,
+        "locality_penalty": 1.5,
+    },
+    "audio": {
+        "sample_rate": 16000,
+        "model_path": "model",
+    },
+    "debug": {
+        "perf_log": False,
+    }
+}
+
+def load_config(config_path: str = None) -> dict:
+    """
+    Loads configuration from `.clicue.toml` or `~/.config/clicue/config.toml`.
+    Falls back to DEFAULT_CONFIG.
+    """
+    cfg = {k: dict(v) for k, v in DEFAULT_CONFIG.items()}
+
+    paths_to_check = []
+    if config_path:
+        paths_to_check.append(config_path)
+    paths_to_check.extend([
+        ".clicue.toml",
+        os.path.expanduser("~/.config/clicue/config.toml"),
+    ])
+
+    for path in paths_to_check:
+        if os.path.isfile(path):
+            try:
+                with open(path, "rb") as f:
+                    file_cfg = tomllib.load(f)
+                    for sec, vals in file_cfg.items():
+                        if sec in cfg and isinstance(vals, dict):
+                            cfg[sec].update(vals)
+                        else:
+                            cfg[sec] = vals
+                break
+            except Exception as e:
+                print(f"Warning: Failed to parse config file '{path}': {e}", file=sys.stderr)
+
+    return cfg

clicue-0.1.2/src/clicue/fountain.py

@@ -0,0 +1,91 @@
+import re
+
+HEADER_KEYWORDS = {"title:", "author:", "authors:", "draft date:", "date:", "contact:", "copyright:", "notes:"}
+
+class ParsedScript:
+    def __init__(self, words: list[str], cues: list[str], para_starts: list[bool]):
+        self.words = words
+        self.cues = cues
+        self.para_starts = para_starts
+
+    def __len__(self):
+        return len(self.words)
+
+def is_header_line(line: str) -> bool:
+    low = line.strip().lower()
+    return any(low.startswith(k) for k in HEADER_KEYWORDS)
+
+def is_scene_heading(line: str) -> bool:
+    stripped = line.strip()
+    if re.match(r"^(INT\.|EXT\.|EST\.|INT\./EXT\.|EXT\./INT\.|\.)", stripped, re.IGNORECASE):
+        return True
+    return False
+
+def is_character_name(line: str) -> bool:
+    stripped = line.strip()
+    if stripped.isupper() and 0 < len(stripped) < 30 and not is_scene_heading(stripped):
+        return True
+    return False
+
+def parse_fountain(content: str) -> ParsedScript:
+    """
+    Parses Fountain or markdown script content.
+    Extracts spoken dialogue words while tracking active stage cues ([Screen Recording...])
+    and paragraph boundaries for teleprompter formatting.
+    """
+    lines = content.splitlines()
+    
+    words = []
+    cues = []
+    para_starts = []
+
+    current_cue = ""
+    in_header = True
+    next_is_para_start = True
+
+    for line in lines:
+        stripped = line.strip()
+
+        if not stripped:
+            next_is_para_start = True
+            continue
+
+        # Check for metadata header
+        if in_header:
+            if is_header_line(line):
+                continue
+            else:
+                in_header = False
+
+        # Check for stage direction / bracketed cues [Screen Recording: ...]
+        bracket_cues = re.findall(r"\[(.*?)\]", line)
+        if bracket_cues:
+            raw_cue = bracket_cues[-1].strip()
+            # Strip redundant prefixes like "Screen Recording:", "Visual:", etc.
+            clean_cue = re.sub(r"^(Screen Recording|Visual|Audio|Note|Action):\s*", "", raw_cue, flags=re.IGNORECASE)
+            current_cue = clean_cue
+
+        if is_scene_heading(line):
+            continue
+
+        if is_character_name(line):
+            continue
+
+        # Clean spoken text by removing [...] and (...)
+        line_clean = re.sub(r"\[.*?\]", "", line)
+        line_clean = re.sub(r"\(.*?\)", "", line_clean).strip()
+
+        if line_clean:
+            line_words = line_clean.split()
+            for i, w in enumerate(line_words):
+                words.append(w)
+                cues.append(current_cue)
+                # First word of a line/paragraph gets the paragraph start flag
+                para_starts.append(next_is_para_start and (i == 0))
+            
+            next_is_para_start = False
+
+    return ParsedScript(words=words, cues=cues, para_starts=para_starts)
+
+def parse_fountain_words(content: str) -> list[str]:
+    return parse_fountain(content).words

clicue-0.1.2/src/clicue/listener.py

@@ -0,0 +1,12 @@
+from clicue.stt.vosk_engine import VoskSTTListener
+
+# Backward compatibility alias
+STTListener = VoskSTTListener
+
+if __name__ == "__main__":
+    listener = STTListener()
+    try:
+        for text in listener.listen():
+            print(f"Recognized: {text}")
+    except KeyboardInterrupt:
+        print("\nStopped listening.")

clicue-0.1.2/src/clicue/main.py

@@ -0,0 +1,224 @@
+import argparse
+import sys
+from rich.live import Live
+
+from clicue.aligner import Aligner
+from clicue.scroller import TUIScroller
+from clicue.stt import get_stt_listener
+from clicue.fountain import parse_fountain, ParsedScript
+from clicue.config import load_config
+
+
+def parse_script_from_file(file_obj, raw=False) -> ParsedScript:
+    content = file_obj.read()
+    if raw:
+        words = content.split()
+        return ParsedScript(
+            words=words,
+            cues=[""] * len(words),
+            para_starts=[i == 0 for i in range(len(words))]
+        )
+    return parse_fountain(content)
+
+def parse_words_from_file(file_obj, raw=False):
+    return parse_script_from_file(file_obj, raw).words
+
+import select
+import termios
+import tty
+
+class KeyboardListener:
+    def __enter__(self):
+        self.old_settings = None
+        if sys.stdin.isatty():
+            try:
+                self.old_settings = termios.tcgetattr(sys.stdin)
+                tty.setcbreak(sys.stdin.fileno())
+            except Exception:
+                pass
+        return self
+
+    def __exit__(self, type, value, traceback):
+        if self.old_settings and sys.stdin.isatty():
+            try:
+                termios.tcsetattr(sys.stdin, termios.TCSADRAIN, self.old_settings)
+            except Exception:
+                pass
+
+    def get_key(self) -> str | None:
+        if not sys.stdin.isatty():
+            return None
+        dr, _, _ = select.select([sys.stdin], [], [], 0)
+        if dr:
+            ch = sys.stdin.read(1)
+            if ch == '\x1b':
+                dr2, _, _ = select.select([sys.stdin], [], [], 0.01)
+                if dr2:
+                    ch2 = sys.stdin.read(1)
+                    if ch2 == '[':
+                        dr3, _, _ = select.select([sys.stdin], [], [], 0.01)
+                        if dr3:
+                            ch3 = sys.stdin.read(1)
+                            if ch3 == 'D':
+                                return 'LEFT'
+                            elif ch3 == 'C':
+                                return 'RIGHT'
+            return ch
+        return None
+
+def main(args=None):
+    parser = argparse.ArgumentParser(description="clicue - teleprompter script scroller")
+    parser.add_argument(
+        "script",
+        nargs="?",
+        type=argparse.FileType("r"),
+        default=sys.stdin,
+        help="Path to the script file (or '-' for stdin). If omitted, reads from stdin.",
+    )
+    parser.add_argument(
+        "--config",
+        default=None,
+        help="Path to a TOML configuration file."
+    )
+    parser.add_argument(
+        "--window-size",
+        type=int,
+        default=None,
+        help="Number of upcoming words to display in look-ahead."
+    )
+    parser.add_argument(
+        "--past-size",
+        type=int,
+        default=None,
+        help="Number of past words to display in look-behind."
+    )
+    parser.add_argument(
+        "--max-lookahead",
+        type=int,
+        default=None,
+        help="Maximum word distance to search ahead for alignment."
+    )
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=None,
+        help="Fuzzy match confidence threshold (0.0 - 100.0)."
+    )
+    parser.add_argument(
+        "--perf-log",
+        action="store_true",
+        help="Log performance metrics to stderr."
+    )
+    parser.add_argument(
+        "--engine",
+        default="vosk",
+        help="STT engine plugin to use (default: vosk)."
+    )
+    parser.add_argument(
+        "--model-path",
+        default=None,
+        help="Path to the model directory."
+    )
+    parser.add_argument(
+        "--device",
+        default=None,
+        help="Audio input device ID or name."
+    )
+    parser.add_argument(
+        "--audio-file",
+        default=None,
+        help="Path to a pre-recorded WAV audio file to use instead of live microphone input."
+    )
+    parser.add_argument(
+        "--raw",
+        action="store_true",
+        help="Do not parse Fountain syntax; read all text literally."
+    )
+    parser.add_argument(
+        "--list-devices",
+        action="store_true",
+        help="List available audio input devices and exit."
+    )
+    
+    parsed_args = parser.parse_args(args)
+
+    if parsed_args.list_devices:
+        import sounddevice as sd
+        print("Available Audio Devices:")
+        print(sd.query_devices())
+        return
+
+    # Load TOML config and merge with CLI arguments
+    cfg = load_config(parsed_args.config)
+    
+    engine_name = parsed_args.engine or cfg.get("audio", {}).get("engine", "vosk")
+    window_size = parsed_args.window_size or cfg["scroller"]["window_size"]
+    past_size = parsed_args.past_size or cfg["scroller"]["past_size"]
+    max_lookahead = parsed_args.max_lookahead or cfg["aligner"]["max_lookahead"]
+    threshold = parsed_args.threshold or cfg["aligner"]["threshold"]
+    locality_penalty = cfg["aligner"].get("locality_penalty", 1.5)
+    model_path = parsed_args.model_path or cfg["audio"]["model_path"]
+    perf_log = parsed_args.perf_log or cfg["debug"]["perf_log"]
+
+    script = parse_script_from_file(parsed_args.script, raw=parsed_args.raw)
+    
+    if not script.words:
+        print("Script is empty.")
+        return 0
+        
+    device_param = parsed_args.device
+    if device_param is not None and device_param.isdigit():
+        device_param = int(device_param)
+
+    aligner = Aligner(
+        script.words,
+        max_lookahead=max_lookahead,
+        threshold=threshold,
+        locality_penalty=locality_penalty,
+        perf_log=perf_log
+    )
+    scroller = TUIScroller(script, window_size=window_size, past_size=past_size)
+    listener = get_stt_listener(engine_name=engine_name, model_path=model_path, device=device_param)
+    
+    audio_stream = listener.listen_file(parsed_args.audio_file) if parsed_args.audio_file else listener.listen()
+
+    current_idx = 0
+    is_paused = False
+
+    try:
+        with KeyboardListener() as kbd:
+            with Live(scroller.render(0, is_paused=False), refresh_per_second=15, auto_refresh=False, screen=True) as live:
+                for text in audio_stream:
+                    # Check non-blocking hotkey input
+                    key = kbd.get_key()
+                    if key in (' ', 'p'):
+                        is_paused = not is_paused
+                        live.update(scroller.render(current_idx, is_paused=is_paused), refresh=True)
+                    elif key in ('LEFT', 'b'):
+                        current_idx = max(0, current_idx - 5)
+                        aligner.current_index = current_idx
+                        live.update(scroller.render(current_idx, is_paused=is_paused), refresh=True)
+                    elif key in ('RIGHT', 'f'):
+                        current_idx = min(len(script.words) - 1, current_idx + 5)
+                        aligner.current_index = current_idx
+                        live.update(scroller.render(current_idx, is_paused=is_paused), refresh=True)
+                    elif key == 'q':
+                        break
+
+                    # Advance cursor with STT only if not paused
+                    if not is_paused:
+                        new_idx = aligner.advance(text)
+                        if new_idx != current_idx:
+                            current_idx = new_idx
+                            live.update(scroller.render(current_idx, is_paused=is_paused), refresh=True)
+
+                    if current_idx >= len(script.words):
+                        break
+    except KeyboardInterrupt:
+        pass
+
+    return 0
+
+if __name__ == "__main__":
+    main()
+

clicue-0.1.2/src/clicue/scroller.py

@@ -0,0 +1,110 @@
+from rich.console import Console
+from rich.text import Text
+from rich.console import Group
+from rich.padding import Padding
+from clicue.fountain import ParsedScript
+
+class TUIScroller:
+    def __init__(self, script: ParsedScript, window_size: int = 38, past_size: int = 9):
+        if isinstance(script, ParsedScript):
+            self.script = script
+        else:
+            self.script = ParsedScript(
+                words=script,
+                cues=[""] * len(script),
+                para_starts=[i == 0 for i in range(len(script))]
+            )
+
+        self.window_size = window_size
+        self.past_size = past_size
+        self.console = Console()
+
+        # Precompute paragraph start word indices
+        self.para_starts_indices = [
+            i for i, is_start in enumerate(self.script.para_starts) if is_start
+        ]
+        if not self.para_starts_indices:
+            self.para_starts_indices = [0]
+
+    def _get_current_para_index(self, current_index: int) -> int:
+        for p_idx in range(len(self.para_starts_indices) - 1, -1, -1):
+            if self.para_starts_indices[p_idx] <= current_index:
+                return p_idx
+        return 0
+
+    def render(self, current_index: int, is_paused: bool = False) -> Group:
+        """
+        Renders the TUI layout with player controls status bar:
+        - Top Header: Player state ([TRACKING ▶] or [PAUSED ⏸]), stage cue, and hotkey guide.
+        - Text Body: Anchored at paragraph boundaries for zero-reflow teleprompter viewing.
+        """
+        current_index = max(0, min(current_index, len(self.script) - 1)) if len(self.script) > 0 else 0
+        
+        # 1. Player Controls & Stage Cue Header
+        header_text = Text()
+
+        if is_paused:
+            header_text.append("[PAUSED ⏸] ", style="bold black on yellow")
+        else:
+            header_text.append("[TRACKING ▶] ", style="bold white on green")
+
+        active_cue = self.script.cues[current_index] if len(self.script.cues) > current_index else ""
+        if active_cue:
+            header_text.append(" 🎬 ", style="yellow")
+            header_text.append(active_cue, style="bold yellow")
+        else:
+            header_text.append(" 🎬 ", style="dim yellow")
+            header_text.append("(no active cue)", style="dim yellow")
+
+        # Hotkey Help Bar
+        footer_help = Text()
+        footer_help.append("[Space]: Pause/Resume  |  [← / b]: Rewind 5w  |  [→ / f]: Skip 5w  |  [q]: Quit", style="dim cyan")
+
+        # 2. Text Body with Paragraph-Anchored Stationary Layout
+        p_idx = self._get_current_para_index(current_index)
+        prev_p_idx = max(0, p_idx - 1)
+        start_index = self.para_starts_indices[prev_p_idx]
+
+        end_index = min(
+            start_index + max(self.window_size + self.past_size, current_index - start_index + self.window_size),
+            len(self.script.words)
+        )
+
+        body_text = Text()
+
+        for idx in range(start_index, end_index):
+            word = self.script.words[idx]
+
+            if idx > start_index and self.script.para_starts[idx]:
+                body_text.append("\n\n")
+
+            if idx < current_index:
+                body_text.append(word, style="dim white")
+            elif idx == current_index:
+                body_text.append(word, style="bold bright_green")
+            else:
+                body_text.append(word, style="white")
+
+            body_text.append(" ")
+
+        return Group(
+            Padding(header_text, (0, 0, 0, 0)),
+            Padding(footer_help, (0, 0, 1, 0)),
+            Padding(body_text, (0, 0, 0, 0))
+        )
+
+    def render_text(self, current_index: int, is_paused: bool = False):
+        return self.render(current_index, is_paused=is_paused)
+
+    def display(self, current_index: int, is_paused: bool = False):
+        self.console.clear()
+        self.console.print(self.render(current_index, is_paused=is_paused))
+
+if __name__ == "__main__":
+    import time
+    words = ["Hello", "world", "this", "is", "a", "test"]
+    script = ParsedScript(words=words, cues=["Screen recording"]*6, para_starts=[True, False, False, True, False, False])
+    scroller = TUIScroller(script)
+    for i in range(len(words)):
+        scroller.display(i)
+        time.sleep(0.3)

clicue-0.1.2/src/clicue/stt/__init__.py

@@ -0,0 +1,15 @@
+from clicue.stt.base import BaseSTTListener
+from clicue.stt.vosk_engine import VoskSTTListener
+
+STT_ENGINES = {
+    "vosk": VoskSTTListener,
+}
+
+def get_stt_listener(engine_name: str = "vosk", **kwargs) -> BaseSTTListener:
+    """
+    Factory function to instantiate STT listener plugins by engine name.
+    """
+    engine_name = engine_name.lower().strip()
+    if engine_name not in STT_ENGINES:
+        raise ValueError(f"Unknown STT engine '{engine_name}'. Available engines: {list(STT_ENGINES.keys())}")
+    return STT_ENGINES[engine_name](**kwargs)

clicue-0.1.2/src/clicue/stt/base.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+from typing import Iterator
+
+class BaseSTTListener(ABC):
+    """
+    Abstract base class for all STT listener plugins in clicue.
+    """
+
+    @abstractmethod
+    def listen(self, device=None) -> Iterator[str]:
+        """
+        Listens to continuous live audio input and yields recognized text strings.
+        """
+        pass
+
+    def listen_file(self, audio_file_path: str) -> Iterator[str]:
+        """
+        Optional: Processes a WAV audio file and yields recognized text strings.
+        """
+        raise NotImplementedError("File streaming is not implemented for this STT engine.")

clicue-0.1.2/src/clicue/stt/vosk_engine.py

@@ -0,0 +1,91 @@
+import queue
+import sys
+import json
+import sounddevice as sd
+from vosk import Model, KaldiRecognizer, SetLogLevel
+
+from clicue.stt.base import BaseSTTListener
+
+# Suppress Vosk C++ logs
+SetLogLevel(-1)
+
+class VoskSTTListener(BaseSTTListener):
+    def __init__(self, model_path="model", sample_rate=16000, device=None):
+        self.sample_rate = sample_rate
+        self.device = device
+        self.model_path = model_path
+        try:
+            self.model = Model(model_path)
+        except Exception as e:
+            print(f"Error loading Vosk model from '{model_path}': {e}", file=sys.stderr)
+            print("Please download a model from https://alphacephei.com/vosk/models and extract it to that path.", file=sys.stderr)
+            sys.exit(1)
+            
+        self.recognizer = KaldiRecognizer(self.model, self.sample_rate)
+        self.q = queue.Queue()
+
+    def _audio_callback(self, indata, frames, time, status):
+        if status:
+            print(status, file=sys.stderr)
+        self.q.put(bytes(indata))
+
+    def listen_file(self, audio_file_path: str):
+        import wave
+        import time
+
+        try:
+            wf = wave.open(audio_file_path, "rb")
+        except Exception as e:
+            print(f"Error opening audio file '{audio_file_path}': {e}", file=sys.stderr)
+            return
+
+        rec = KaldiRecognizer(self.model, wf.getframerate())
+        chunk_size = 4000
+
+        while True:
+            data = wf.readframes(chunk_size)
+            if len(data) == 0:
+                break
+            time.sleep(0.1)
+            if rec.AcceptWaveform(data):
+                result = json.loads(rec.Result())
+                text = result.get("text", "")
+                if text:
+                    yield text
+            else:
+                result = json.loads(rec.PartialResult())
+                text = result.get("partial", "")
+                if text:
+                    yield text
+
+        result = json.loads(rec.FinalResult())
+        text = result.get("text", "")
+        if text:
+            yield text
+
+    def listen(self, device=None):
+        target_device = device if device is not None else self.device
+        try:
+            with sd.RawInputStream(
+                samplerate=self.sample_rate,
+                blocksize=8000,
+                device=target_device,
+                dtype='int16',
+                channels=1,
+                callback=self._audio_callback
+            ):
+                while True:
+                    data = self.q.get()
+                    if self.recognizer.AcceptWaveform(data):
+                        result = json.loads(self.recognizer.Result())
+                        text = result.get("text", "")
+                        if text:
+                            yield text
+                    else:
+                        result = json.loads(self.recognizer.PartialResult())
+                        text = result.get("partial", "")
+                        if text:
+                            yield text
+        except sd.PortAudioError as e:
+            print(f"\n[Error] Could not open audio input device ({target_device}): {e}", file=sys.stderr)
+            raise