talks-reducer 0.7.1__tar.gz → 0.7.2__tar.gz

{talks_reducer-0.7.1 → talks_reducer-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: talks-reducer
-Version: 0.7.1
+Version: 0.7.2
 Summary: CLI for speeding up long-form talks by removing silence
 Author: Talks Reducer Maintainers
 License-Expression: MIT
@@ -174,6 +174,28 @@ The helper wraps the Gradio API exposed by `server.py`, waits for processing to
 path you provide. Pass `--small` to mirror the **Small video** checkbox or `--print-log` to stream the server log after the
 download finishes.
 
+## Faster PyInstaller builds
+
+PyInstaller spends most of its time walking imports. To keep GUI builds snappy:
+
+- Create a dedicated virtual environment for packaging the GUI and install only
+  the runtime dependencies you need (for example `pip install -r
+  requirements.txt -r scripts/requirements-pyinstaller.txt`). Avoid installing
+  heavy ML stacks such as Torch or TensorFlow in that environment so PyInstaller
+  never attempts to analyze them.
+- Use the committed `talks-reducer.spec` file via `./scripts/build-gui.sh`.
+  The spec excludes Torch, TensorFlow, TensorBoard, torchvision/torchaudio,
+  Pandas, Qt bindings, setuptools' vendored helpers, and other bulky modules
+  that previously slowed the analysis stage. Set
+  `PYINSTALLER_EXTRA_EXCLUDES=module1,module2` if you need to drop additional
+  imports for an experimental build.
+- Keep optional imports in the codebase lazy (wrapped in `try/except` or moved
+  inside functions) so the analyzer only sees the dependencies required for the
+  shipping GUI.
+
+The script keeps incremental build artifacts in `build/` between runs. Pass
+`--clean` to `scripts/build-gui.sh` when you want a full rebuild.
+
 ## Contributing
 See `CONTRIBUTION.md` for development setup details and guidance on sharing improvements.
 

talks_reducer-0.7.1/talks_reducer.egg-info/PKG-INFO → talks_reducer-0.7.2/README.md

@@ -1,181 +1,175 @@
-Metadata-Version: 2.4
-Name: talks-reducer
-Version: 0.7.1
-Summary: CLI for speeding up long-form talks by removing silence
-Author: Talks Reducer Maintainers
-License-Expression: MIT
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: audiotsm>=0.1.2
-Requires-Dist: scipy>=1.10.0
-Requires-Dist: numpy>=1.22.0
-Requires-Dist: tqdm>=4.65.0
-Requires-Dist: tkinterdnd2>=0.3.0
-Requires-Dist: Pillow>=9.0.0
-Requires-Dist: pystray>=0.19.5
-Requires-Dist: imageio-ffmpeg>=0.4.8
-Requires-Dist: gradio>=4.0.0
-Provides-Extra: dev
-Requires-Dist: build>=1.0.0; extra == "dev"
-Requires-Dist: twine>=4.0.0; extra == "dev"
-Requires-Dist: pytest>=7.0.0; extra == "dev"
-Requires-Dist: black>=23.0.0; extra == "dev"
-Requires-Dist: isort>=5.12.0; extra == "dev"
-Requires-Dist: bump-my-version>=0.5.0; extra == "dev"
-Requires-Dist: pyinstaller>=6.4.0; extra == "dev"
-Dynamic: license-file
-
-# Talks Reducer 
-
-Talks Reducer shortens long-form presentations by removing silent gaps and optionally re-encoding them to smaller files. The
-project was renamed from **jumpcutter** to emphasize its focus on conference talks and screencasts.
-
-![Main demo](docs/assets/screencast-main.gif)
-
-## Example
-- 1h 37m, 571 MB — Original OBS video recording
-- 1h 19m, 751 MB — Talks Reducer
-- 1h 19m, 171 MB — Talks Reducer `--small`
-
-## Changelog
-
-See [CHANGELOG.md](CHANGELOG.md).
-
-## Install GUI (Windows, macOS)
-Go to the [releases page](https://github.com/popstas/talks-reducer/releases) and download the appropriate artifact:
-
-- **Windows** — `talks-reducer-windows-0.4.0.zip`
-- **macOS** — `talks-reducer.app.zip`
-
-  > **Troubleshooting:** If launching the bundle (or running `python -m talks_reducer.gui`) prints `macOS 26 (2600) or later required, have instead 16 (1600)!`, make sure you're using a Python build that ships a modern Tk. The stock [python.org 3.13.5 installer](https://www.python.org/downloads/release/python-3135/) includes Tk 8.6 and has been verified to work.
-
-When extracted on Windows the bundled `talks-reducer.exe` behaves like running
-`python -m talks_reducer.gui`: double-clicking it launches the GUI
-and passing a video file path (for example via *Open with…* or drag-and-drop
-onto the executable) automatically queues that recording for processing.
-
-## Install CLI (Linux, Windows, macOS)
-```
-pip install talks-reducer
-```
-
-**Note:** FFmpeg is now bundled automatically with the package, so you don't need to install it separately. You you need, don't know actually.
-
-The `--small` preset applies a 720p video scale and 128 kbps audio bitrate, making it useful for sharing talks over constrained
-connections. Without `--small`, the script aims to preserve original quality while removing silence.
-
-Example CLI usage:
-
-```sh
-talks-reducer --small input.mp4
-```
-
-Need to offload work to a remote Talks Reducer server? Pass `--url` with the
-server address and the CLI will upload the input, wait for processing to finish,
-and download the rendered video. You can also provide `--host` to expand to the
-default Talks Reducer port (`http://<host>:9005`):
-
-```sh
-talks-reducer --url http://localhost:9005 demo.mp4
-talks-reducer --host 192.168.1.42 demo.mp4
-```
-
-Remote jobs respect the same timing controls as the local CLI. Provide
-`--silent-threshold`, `--sounded-speed`, or `--silent-speed` to tweak how the
-server trims and accelerates segments without falling back to local mode.
-
-Want to see progress as the remote server works? Add `--server-stream` so the
-CLI prints live progress bars and log lines while you wait for the download.
-
-### Speech detection
-
-Talks Reducer now relies on its built-in volume thresholding to detect speech. Adjust `--silent_threshold` if you need to fine-tune when segments count as silence. Dropping the optional Silero VAD integration keeps the install lightweight and avoids pulling in PyTorch.
-
-When CUDA-capable hardware is available the pipeline leans on GPU encoders to keep export times low, but it still runs great on
-CPUs.
-
-## Simple web server
-
-Prefer a lightweight browser interface? Launch the Gradio-powered simple mode with:
-
-```sh
-talks-reducer server
-```
-
-The browser UI mirrors the CLI timing controls with sliders for the silent
-threshold and playback speeds, so you can tune exports without leaving the
-remote workflow.
-
-Want the server to live in your system tray instead of a terminal window? Use:
-
-```sh
-talks-reducer server-tray
-```
-
-Bundled Windows builds include the same behaviour: run
-`talks-reducer.exe --server` to launch the tray-managed server directly from the
-desktop shortcut without opening the GUI first.
-
-Pass `--debug` to print verbose logs about the tray icon lifecycle, and
-`--tray-mode pystray-detached` to try pystray's alternate detached runner. If
-the icon backend refuses to appear, fall back to `--tray-mode headless` to keep
-the web server running without a tray process. The tray menu highlights the
-running Talks Reducer version and includes an **Open GUI**
-item (also triggered by double-clicking the icon) that launches the desktop
-Talks Reducer interface alongside an **Open WebUI** entry that opens the Gradio
-page in your browser. Close the GUI window to return to the tray without
-stopping the server. Launch the tray explicitly whenever you need it—either run
-`talks-reducer server-tray` directly or start the GUI with
-`python -m talks_reducer.gui --server` to boot the tray-managed server instead
-of the desktop window. The GUI now runs standalone and no longer spawns the tray
-automatically; the deprecated `--no-tray` flag is ignored for compatibility.
-The tray command itself never launches the GUI automatically, so use the menu
-item (or relaunch the GUI separately) whenever you want to reopen it. The tray
-no longer opens a browser automatically—pass `--open-browser` if you prefer the
-web page to launch as soon as the server is ready.
-
-This opens a local web page featuring a drag-and-drop upload zone, a **Small video** checkbox that mirrors the CLI preset, a live
-progress indicator, and automatic previews of the processed output. The page header and browser tab title include the current
-Talks Reducer version so you can confirm which build the server is running. Once the job completes you can inspect the resulting
-compression ratio and download the rendered video directly from the page.
-
-The desktop GUI mirrors this behaviour. Open **Advanced** settings to provide a
-server URL and click **Discover** to scan your local network for Talks Reducer
-instances listening on port `9005`. The button now updates with the discovery
-progress, showing the scanned/total host count as `scanned / total`. A new
-**Processing mode** toggle lets you decide whether work stays local or uploads
-to the configured server—the **Remote** option becomes available as soon as a
-URL is supplied. Leave the toggle on **Local** to keep rendering on this
-machine even if a server is saved; switch to **Remote** to hand jobs off while
-the GUI downloads the finished files automatically.
-
-### Uploading and retrieving a processed video
-
-1. Open the printed `http://localhost:<port>` address (the default port is `9005`).
-2. Drag a video onto the **Video file** drop zone or click to browse and select one from disk.
-3. **Small video** starts enabled to apply the 720p/128 kbps preset. Clear the box before the upload finishes if you want to keep the original resolution and bitrate.
-4. Wait for the progress bar and log to report completion—the interface queues work automatically after the file arrives.
-5. Watch the processed preview in the **Processed video** player and click **Download processed file** to save the result locally.
-
-Need to change where the server listens? Run `talks-reducer server --host 0.0.0.0 --port 7860` (or any other port) to bind to a
-different address.
-
-### Automating uploads from the command line
-
-Prefer to script uploads instead of using the browser UI? Start the server and use the bundled helper to submit a job and save
-the processed video locally:
-
-```sh
-python -m talks_reducer.service_client --server http://127.0.0.1:9005/ --input demo.mp4 --output output/demo_processed.mp4
-```
-
-The helper wraps the Gradio API exposed by `server.py`, waits for processing to complete, then copies the rendered file to the
-path you provide. Pass `--small` to mirror the **Small video** checkbox or `--print-log` to stream the server log after the
-download finishes.
-
-## Contributing
-See `CONTRIBUTION.md` for development setup details and guidance on sharing improvements.
-
-## License
-Talks Reducer is released under the MIT License. See `LICENSE` for the full text.
+# Talks Reducer 
+
+Talks Reducer shortens long-form presentations by removing silent gaps and optionally re-encoding them to smaller files. The
+project was renamed from **jumpcutter** to emphasize its focus on conference talks and screencasts.
+
+![Main demo](docs/assets/screencast-main.gif)
+
+## Example
+- 1h 37m, 571 MB — Original OBS video recording
+- 1h 19m, 751 MB — Talks Reducer
+- 1h 19m, 171 MB — Talks Reducer `--small`
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md).
+
+## Install GUI (Windows, macOS)
+Go to the [releases page](https://github.com/popstas/talks-reducer/releases) and download the appropriate artifact:
+
+- **Windows** — `talks-reducer-windows-0.4.0.zip`
+- **macOS** — `talks-reducer.app.zip`
+
+  > **Troubleshooting:** If launching the bundle (or running `python -m talks_reducer.gui`) prints `macOS 26 (2600) or later required, have instead 16 (1600)!`, make sure you're using a Python build that ships a modern Tk. The stock [python.org 3.13.5 installer](https://www.python.org/downloads/release/python-3135/) includes Tk 8.6 and has been verified to work.
+
+When extracted on Windows the bundled `talks-reducer.exe` behaves like running
+`python -m talks_reducer.gui`: double-clicking it launches the GUI
+and passing a video file path (for example via *Open with…* or drag-and-drop
+onto the executable) automatically queues that recording for processing.
+
+## Install CLI (Linux, Windows, macOS)
+```
+pip install talks-reducer
+```
+
+**Note:** FFmpeg is now bundled automatically with the package, so you don't need to install it separately. You you need, don't know actually.
+
+The `--small` preset applies a 720p video scale and 128 kbps audio bitrate, making it useful for sharing talks over constrained
+connections. Without `--small`, the script aims to preserve original quality while removing silence.
+
+Example CLI usage:
+
+```sh
+talks-reducer --small input.mp4
+```
+
+Need to offload work to a remote Talks Reducer server? Pass `--url` with the
+server address and the CLI will upload the input, wait for processing to finish,
+and download the rendered video. You can also provide `--host` to expand to the
+default Talks Reducer port (`http://<host>:9005`):
+
+```sh
+talks-reducer --url http://localhost:9005 demo.mp4
+talks-reducer --host 192.168.1.42 demo.mp4
+```
+
+Remote jobs respect the same timing controls as the local CLI. Provide
+`--silent-threshold`, `--sounded-speed`, or `--silent-speed` to tweak how the
+server trims and accelerates segments without falling back to local mode.
+
+Want to see progress as the remote server works? Add `--server-stream` so the
+CLI prints live progress bars and log lines while you wait for the download.
+
+### Speech detection
+
+Talks Reducer now relies on its built-in volume thresholding to detect speech. Adjust `--silent_threshold` if you need to fine-tune when segments count as silence. Dropping the optional Silero VAD integration keeps the install lightweight and avoids pulling in PyTorch.
+
+When CUDA-capable hardware is available the pipeline leans on GPU encoders to keep export times low, but it still runs great on
+CPUs.
+
+## Simple web server
+
+Prefer a lightweight browser interface? Launch the Gradio-powered simple mode with:
+
+```sh
+talks-reducer server
+```
+
+The browser UI mirrors the CLI timing controls with sliders for the silent
+threshold and playback speeds, so you can tune exports without leaving the
+remote workflow.
+
+Want the server to live in your system tray instead of a terminal window? Use:
+
+```sh
+talks-reducer server-tray
+```
+
+Bundled Windows builds include the same behaviour: run
+`talks-reducer.exe --server` to launch the tray-managed server directly from the
+desktop shortcut without opening the GUI first.
+
+Pass `--debug` to print verbose logs about the tray icon lifecycle, and
+`--tray-mode pystray-detached` to try pystray's alternate detached runner. If
+the icon backend refuses to appear, fall back to `--tray-mode headless` to keep
+the web server running without a tray process. The tray menu highlights the
+running Talks Reducer version and includes an **Open GUI**
+item (also triggered by double-clicking the icon) that launches the desktop
+Talks Reducer interface alongside an **Open WebUI** entry that opens the Gradio
+page in your browser. Close the GUI window to return to the tray without
+stopping the server. Launch the tray explicitly whenever you need it—either run
+`talks-reducer server-tray` directly or start the GUI with
+`python -m talks_reducer.gui --server` to boot the tray-managed server instead
+of the desktop window. The GUI now runs standalone and no longer spawns the tray
+automatically; the deprecated `--no-tray` flag is ignored for compatibility.
+The tray command itself never launches the GUI automatically, so use the menu
+item (or relaunch the GUI separately) whenever you want to reopen it. The tray
+no longer opens a browser automatically—pass `--open-browser` if you prefer the
+web page to launch as soon as the server is ready.
+
+This opens a local web page featuring a drag-and-drop upload zone, a **Small video** checkbox that mirrors the CLI preset, a live
+progress indicator, and automatic previews of the processed output. The page header and browser tab title include the current
+Talks Reducer version so you can confirm which build the server is running. Once the job completes you can inspect the resulting
+compression ratio and download the rendered video directly from the page.
+
+The desktop GUI mirrors this behaviour. Open **Advanced** settings to provide a
+server URL and click **Discover** to scan your local network for Talks Reducer
+instances listening on port `9005`. The button now updates with the discovery
+progress, showing the scanned/total host count as `scanned / total`. A new
+**Processing mode** toggle lets you decide whether work stays local or uploads
+to the configured server—the **Remote** option becomes available as soon as a
+URL is supplied. Leave the toggle on **Local** to keep rendering on this
+machine even if a server is saved; switch to **Remote** to hand jobs off while
+the GUI downloads the finished files automatically.
+
+### Uploading and retrieving a processed video
+
+1. Open the printed `http://localhost:<port>` address (the default port is `9005`).
+2. Drag a video onto the **Video file** drop zone or click to browse and select one from disk.
+3. **Small video** starts enabled to apply the 720p/128 kbps preset. Clear the box before the upload finishes if you want to keep the original resolution and bitrate.
+4. Wait for the progress bar and log to report completion—the interface queues work automatically after the file arrives.
+5. Watch the processed preview in the **Processed video** player and click **Download processed file** to save the result locally.
+
+Need to change where the server listens? Run `talks-reducer server --host 0.0.0.0 --port 7860` (or any other port) to bind to a
+different address.
+
+### Automating uploads from the command line
+
+Prefer to script uploads instead of using the browser UI? Start the server and use the bundled helper to submit a job and save
+the processed video locally:
+
+```sh
+python -m talks_reducer.service_client --server http://127.0.0.1:9005/ --input demo.mp4 --output output/demo_processed.mp4
+```
+
+The helper wraps the Gradio API exposed by `server.py`, waits for processing to complete, then copies the rendered file to the
+path you provide. Pass `--small` to mirror the **Small video** checkbox or `--print-log` to stream the server log after the
+download finishes.
+
+## Faster PyInstaller builds
+
+PyInstaller spends most of its time walking imports. To keep GUI builds snappy:
+
+- Create a dedicated virtual environment for packaging the GUI and install only
+  the runtime dependencies you need (for example `pip install -r
+  requirements.txt -r scripts/requirements-pyinstaller.txt`). Avoid installing
+  heavy ML stacks such as Torch or TensorFlow in that environment so PyInstaller
+  never attempts to analyze them.
+- Use the committed `talks-reducer.spec` file via `./scripts/build-gui.sh`.
+  The spec excludes Torch, TensorFlow, TensorBoard, torchvision/torchaudio,
+  Pandas, Qt bindings, setuptools' vendored helpers, and other bulky modules
+  that previously slowed the analysis stage. Set
+  `PYINSTALLER_EXTRA_EXCLUDES=module1,module2` if you need to drop additional
+  imports for an experimental build.
+- Keep optional imports in the codebase lazy (wrapped in `try/except` or moved
+  inside functions) so the analyzer only sees the dependencies required for the
+  shipping GUI.
+
+The script keeps incremental build artifacts in `build/` between runs. Pass
+`--clean` to `scripts/build-gui.sh` when you want a full rebuild.
+
+## Contributing
+See `CONTRIBUTION.md` for development setup details and guidance on sharing improvements.
+
+## License
+Talks Reducer is released under the MIT License. See `LICENSE` for the full text.

{talks_reducer-0.7.1 → talks_reducer-0.7.2}/talks_reducer/__about__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"

{talks_reducer-0.7.1 → talks_reducer-0.7.2}/talks_reducer/gui/__init__.py

@@ -325,7 +325,7 @@ class TalksReducerGUI:
 
         self._full_size = (1000, 800)
         self._simple_size = (300, 270)
-        self.root.geometry(f"{self._full_size[0]}x{self._full_size[1]}")
+        # self.root.geometry(f"{self._full_size[0]}x{self._full_size[1]}")
         self.style = self.ttk.Style(self.root)
 
         self._processing_thread: Optional[threading.Thread] = None

{talks_reducer-0.7.1 → talks_reducer-0.7.2}/talks_reducer/gui/layout.py

@@ -3,9 +3,9 @@
 from __future__ import annotations
 
 import sys
-from pathlib import Path
 from typing import TYPE_CHECKING, Callable
 
+from ..icons import find_icon_path
 from ..models import default_temp_folder
 
 if TYPE_CHECKING:  # pragma: no cover - imported for type checking only
@@ -454,37 +454,24 @@ def reset_basic_defaults(gui: "TalksReducerGUI") -> None:
 def apply_window_icon(gui: "TalksReducerGUI") -> None:
     """Configure the application icon when the asset is available."""
 
-    base_path = Path(getattr(sys, "_MEIPASS", Path(__file__).resolve().parent.parent))
-
-    icon_candidates: list[tuple[Path, str]] = []
-    if sys.platform.startswith("win"):
-        icon_candidates.append(
-            (
-                base_path / "talks_reducer" / "resources" / "icons" / "icon.ico",
-                "ico",
-            )
-        )
-    icon_candidates.append(
-        (
-            base_path / "talks_reducer" / "resources" / "icons" / "icon.png",
-            "png",
-        )
+    icon_filenames = (
+        ("app.ico", "app.png")
+        if sys.platform.startswith("win")
+        else ("app.png", "app.ico")
     )
+    icon_path = find_icon_path(filenames=icon_filenames)
+    if icon_path is None:
+        return
 
-    for icon_path, icon_type in icon_candidates:
-        if not icon_path.is_file():
-            continue
-
-        try:
-            if icon_type == "ico" and sys.platform.startswith("win"):
-                # On Windows, iconbitmap works better without the 'default' parameter
-                gui.root.iconbitmap(str(icon_path))
-            else:
-                gui.root.iconphoto(False, gui.tk.PhotoImage(file=str(icon_path)))
-            return
-        except (gui.tk.TclError, Exception):
-            # Missing Tk image support or invalid icon format - try next candidate
-            continue
+    try:
+        if icon_path.suffix.lower() == ".ico" and sys.platform.startswith("win"):
+            # On Windows, iconbitmap works better without the 'default' parameter.
+            gui.root.iconbitmap(str(icon_path))
+        else:
+            gui.root.iconphoto(False, gui.tk.PhotoImage(file=str(icon_path)))
+    except (gui.tk.TclError, Exception):
+        # Missing Tk image support or invalid icon format - fail silently.
+        return
 
 
 def apply_window_size(gui: "TalksReducerGUI", *, simple: bool) -> None:

talks_reducer-0.7.2/talks_reducer/icons.py

@@ -0,0 +1,121 @@
+"""Icon discovery helpers shared across Talks Reducer entry points."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from contextlib import suppress
+from pathlib import Path
+from typing import Iterator, Optional, Sequence
+
+LOGGER = logging.getLogger(__name__)
+
+_ICON_RELATIVE_PATHS: Sequence[Path] = (
+    Path("talks_reducer") / "resources" / "icons",
+    Path("docs") / "assets",
+)
+_ICON_PATH_SUFFIXES: Sequence[Path] = (
+    Path(""),
+    Path("_internal"),
+    Path("Contents") / "Resources",
+    Path("Resources"),
+)
+
+
+def _iter_base_roots(module_file: Optional[Path | str] = None) -> Iterator[Path]:
+    """Yield base directories where icon assets may live."""
+
+    module_path = Path(module_file or __file__).resolve()
+    package_root = module_path.parent
+    project_root = package_root.parent
+
+    seen: set[Path] = set()
+
+    def _yield(path: Optional[Path]) -> Iterator[Path]:
+        if path is None:
+            return iter(())
+        resolved = path.resolve()
+        if resolved in seen:
+            return iter(())
+        seen.add(resolved)
+        return iter((resolved,))
+
+    for root in (
+        package_root,
+        project_root,
+    ):
+        yield from _yield(root)
+
+    frozen_root: Optional[Path] = None
+    frozen_value = getattr(sys, "_MEIPASS", None)
+    if frozen_value:
+        with suppress(Exception):
+            frozen_root = Path(str(frozen_value))
+    if frozen_root is not None:
+        yield from _yield(frozen_root)
+
+    with suppress(Exception):
+        executable_root = Path(sys.executable).resolve().parent
+        yield from _yield(executable_root)
+
+    with suppress(Exception):
+        launcher_root = Path(sys.argv[0]).resolve().parent
+        yield from _yield(launcher_root)
+
+
+def iter_icon_candidates(
+    *,
+    filenames: Sequence[str],
+    relative_paths: Sequence[Path] | None = None,
+    module_file: Optional[Path | str] = None,
+) -> Iterator[Path]:
+    """Yield possible icon paths ordered from most to least specific."""
+
+    if relative_paths is None:
+        relative_paths = _ICON_RELATIVE_PATHS
+
+    seen: set[Path] = set()
+    for base_root in _iter_base_roots(module_file=module_file):
+        for suffix in _ICON_PATH_SUFFIXES:
+            candidate_root = (base_root / suffix).resolve()
+            if candidate_root in seen:
+                continue
+            seen.add(candidate_root)
+            LOGGER.debug("Considering icon root: %s", candidate_root)
+
+            if not candidate_root.exists():
+                LOGGER.debug("Skipping missing icon root: %s", candidate_root)
+                continue
+
+            for relative in relative_paths:
+                candidate_base = (candidate_root / relative).resolve()
+                if not candidate_base.exists():
+                    LOGGER.debug("Skipping missing icon directory: %s", candidate_base)
+                    continue
+                for name in filenames:
+                    candidate = (candidate_base / name).resolve()
+                    LOGGER.debug("Checking icon candidate: %s", candidate)
+                    yield candidate
+
+
+def find_icon_path(
+    *,
+    filenames: Sequence[str],
+    relative_paths: Sequence[Path] | None = None,
+    module_file: Optional[Path | str] = None,
+) -> Optional[Path]:
+    """Return the first existing icon path matching *filenames* or ``None``."""
+
+    for candidate in iter_icon_candidates(
+        filenames=filenames,
+        relative_paths=relative_paths,
+        module_file=module_file,
+    ):
+        if candidate.is_file():
+            LOGGER.info("Found icon at %s", candidate)
+            return candidate
+    LOGGER.warning("Unable to locate Talks Reducer icon; checked %s", filenames)
+    return None
+
+
+__all__ = ["find_icon_path", "iter_icon_candidates"]