framesource 0.3.0__tar.gz

framesource-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [main, tidy]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools_scm needs history/tags for the version
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system libraries for headless OpenCV
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y libgl1 libglib2.0-0
+
+      # The audio extra is deliberately not installed: pyaudio needs portaudio
+      # system packages, and the audio tests importorskip their dependencies.
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          pip install pytest
+
+      - name: Run hardware-free test suite
+        run: pytest -m "not hardware"
+
+  lint:
+    name: lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  typecheck:
+    name: mypy (non-blocking)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: |
+          pip install mypy
+          pip install -e .
+      - run: mypy src/framesource
+
+  build:
+    name: build & twine check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*

framesource-0.3.0/.github/workflows/publish.yaml

@@ -0,0 +1,45 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  # Manual runs must be dispatched from a tag ref (e.g. v0.3.0), otherwise
+  # setuptools_scm produces a dev version that PyPI rejects.
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools_scm derives the version from the tag
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/framesource
+    # Trusted publishing: on pypi.org, add this repo as a trusted publisher
+    # for the "framesource" project with workflow name "publish.yaml" and
+    # environment "pypi" (one-time, manual). No API token is stored in the repo.
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

framesource-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools_scm derives the version from the tag
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # PyPI publishing lives in publish.yaml (same v* tag trigger).
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

framesource-0.3.0/.gitignore

@@ -0,0 +1,104 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# setuptools_scm generated version file
+src/framesource/_version.py
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env.bak/
+venv.bak/
+.venv/
+.github/prompts/
+
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+build/
+dist/
+*.spec
+
+# Installer logs
+debug.log
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# mypy
+.mypy_cache/
+.dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# VS Code
+.vscode/
+
+# Windows
+Thumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Linux
+*~
+
+# Logs
+*.log
+
+# Other
+*.swp
+*.swo
+
+# Project-specific
+src/*/__pycache__/
+src/__pycache__/folder_capture.cpython-311.pyc

framesource-0.3.0/CHANGELOG.md

@@ -0,0 +1,129 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `WebcamCapture` gains `backend` and `fourcc` constructor keyword arguments.
+  `backend` selects the OpenCV capture backend by name (`'msmf'`, `'dshow'`,
+  `'v4l2'`, `'avfoundation'`, `'gstreamer'`, `'ffmpeg'`, `'any'`) or a raw
+  `cv2.CAP_*` int; `fourcc` (e.g. `'MJPG'`) requests a pixel format, applied
+  before the resolution so drivers don't reset it. Fixes uncompressed formats
+  (e.g. YUY2) saturating the USB link and throttling high-resolution capture
+  to single-digit frame rates. `connect()` now logs a warning when it detects
+  an uncompressed format negotiated at 720p or above, and `get_fourcc()`
+  reports the negotiated format.
+
+### Fixed
+
+- Importing `framesource` now disables OpenCV MSMF hardware transforms on
+  Windows (`OPENCV_VIDEOIO_MSMF_ENABLE_HW_TRANSFORMS=0`, via `setdefault` so
+  an explicit user value wins). This cuts webcam open time on affected devices
+  from 20+ seconds to a fraction of a second with no throughput cost. Only
+  effective when `framesource` is imported before `cv2` opens an MSMF device.
+
+## [0.3.0] - 2026-07-12
+
+The "synchronous core" release. The package was renamed, the internal
+threading model was removed in favour of explicit, opt-in concurrency
+helpers, and frames now carry metadata. Existing code keeps working: the
+old import name, factory parameter names, and the OpenCV-compatible
+`isOpened()` / `read()` / `release()` surface are all preserved.
+
+### Added
+
+- `Frame` — an `np.ndarray` subclass returned by `read()`, carrying
+  `timestamp` (wall clock), `monotonic` (for latency/FPS math), `count`,
+  `uuid`, `source`, and a free-form `metadata` dict. Works in any
+  OpenCV/numpy call and survives pickling.
+- `FrameSourceProtocol` — runtime-checkable protocol defining the minimal
+  source contract (`connect`/`disconnect`/`read`/`is_open`), so custom
+  sources can be duck-typed without inheriting `VideoCaptureBase`.
+- `framesource.errors` — `FrameSourceError` base plus
+  `MissingDependencyError` (an `ImportError` carrying the pip-extra install
+  hint), `UnknownSourceTypeError` (a `ValueError`, raised by the factory),
+  and `NotConnectedError`. Existing `except ImportError/ValueError` clauses
+  keep working.
+- `DeviceInfo` — typed, dict-compatible device descriptor returned by
+  `discover()` implementations.
+- Typed constructors with explicit keyword parameters for the consumer
+  sources (`WebcamCapture`, `VideoFileCapture`, `FolderCapture`,
+  `IPCameraCapture`, `ScreenCapture`, `AudioSpectrogramCapture`) and the
+  vendor sources (`BaslerCapture`, `GenicamCapture`, `RealsenseCapture`,
+  `XimeaCapture`, `HuatengCapture`).
+- Capability flags on every source (`supports_exposure`, `supports_gain`,
+  `supports_depth`) replacing `hasattr()` probing.
+- Iterator protocol — `for frame in cap:` yields frames until the source is
+  exhausted.
+- `wait_until_ready(timeout)` — poll until a source actually produces
+  frames (RTSP "connected but not yet streaming").
+- `fps_actual()` — rolling-window measured FPS on the monotonic clock.
+- `framesource.threading_utils` additions: `AsyncFrameSource` (asyncio
+  adapter), `SharedProducer` (one producer, N subscriber queues),
+  `ProducerConsumer` (joinable producer/consumer pair handle), and
+  `FrameProducer.get_stats()` now reports `avg_latency` and warns on high
+  drop rates.
+- `FrameSourceFactory.from_config()` — create a source from a dict or a
+  `.json`/`.yaml` config file (YAML requires PyYAML to be installed).
+- Optional-dependency extras: `audio`, `basler`, `realsense`, `genicam`,
+  `full`. `py.typed` marker shipped.
+- Real-world examples: inference pipeline with back-pressure, record →
+  replay, and source swapping; CI (GitHub Actions) across
+  Ubuntu/Windows × Python 3.9/3.11/3.13; release automation via PyPI
+  trusted publishing.
+
+### Changed
+
+- **Package renamed** to `framesource` (import and PyPI name now match),
+  with a `src/` layout and `sources`/`processors` subpackages.
+- **Synchronous core**: capture classes no longer spawn internal threads.
+  Concurrency is explicit via `framesource.threading_utils`
+  (`simple_frame_producer`, `FrameProducer`, multiprocessing helper).
+  The sole exception is `AudioSpectrogramCapture`'s audio ring-buffer
+  thread, which is inherent to its I/O model.
+- Factory parameters renamed for clarity: `capture_type` → `source_type`,
+  `source` → `source_id` (old names still work, see Deprecated).
+- Library no longer calls `logging.basicConfig()` or prints to stdout; all
+  diagnostics go through per-module loggers.
+- Python floor raised to 3.9 (3.8 is end-of-life).
+- Versioning is tag-driven via `setuptools_scm`.
+- Lint/format tooling consolidated on ruff (replacing black + isort).
+
+### Deprecated
+
+- `import frame_source` — use `import framesource`. The shim (including
+  deep imports like `frame_source.webcam_capture`) warns and will be
+  removed in a future major release.
+- Factory params `capture_type=` / `source=` — use `source_type` /
+  `source_id`. Warn via `DeprecationWarning`; no removal scheduled within
+  0.x.
+- `get_config_schema()` on all sources — UI form schemas belong in the
+  consuming application; typed constructors expose the same information.
+  Scheduled for removal in 0.4.0.
+
+### Removed
+
+- Web-UI residue: `get_available_sources()` and the `display_fields` class
+  attributes.
+- Internal threading API: `start_async()`, `stop()`, `get_latest_frame()`,
+  `_background_capture` (deprecated behaviourally by the synchronous core;
+  the old methods no longer exist).
+
+### Fixed
+
+- `AudioSpectrogramCapture` accepts `freq_range` as a tuple/list as
+  documented, not only as a `"min,max"` string.
+- `FrameSourceFactory.create(connect=False)` no longer leaks the `connect`
+  kwarg into the capture's config.
+- `multiprocess_frame_producer` no longer raises `UnboundLocalError` when
+  source creation fails; queue-full handling is explicit.
+- `readme.md` renamed to `README.md`, fixing sdist builds on
+  case-sensitive filesystems.
+
+[Unreleased]: https://github.com/olkham/FrameSource/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/olkham/FrameSource/releases/tag/v0.3.0

framesource-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Oliver Hamilton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

framesource-0.3.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+recursive-include src/framesource *.py
+recursive-include src/frame_source *.py
+include src/framesource/py.typed