How twabi/framemq works
Project type and purpose
• FrameMQ is a Python library (not a standalone service) that provides real-time video frame transmission over pub/sub platforms (Apache Kafka or MQTT), with optional PSO-based parameter tuning.
File structure
• Top-level package: frameMQ/
• agent/reader.py and agent/writer.py house the Reader and Writer agents (entry points).
• components/reader has frame retrieval and display logic.
• components/writer has frame capture and transfer logic.
• components/common/video_saver.py for optional disk dumps.
• optimizers/PSO contains the PSO algorithm.
• models/models.py defines parameter objects.
• utils/ holds enums and helper functions.
• External config/build: pyproject.toml, requirements.txt, setup.py.
• Tests mirror the component structure under tests/.
README for additional insights
• Supported transports: Kafka, MQTT.
• Two agents: Writer (produce) and Reader (consume).
• PSO optimizer can tune partitions, chunk size, quality.
• Video encoding: TurboJPEG; display: OpenCV+GStreamer.
• Clients invoke Writer.start() / Reader.start().
Main components & interactions
a. Components
• Client Application (user code)
• Writer Agent (frameMQ.agent.writer.Writer)
• Writer Components
– FrameCapture (video capture + encoding)
– FrameTransfer (chunking + pub/sub publish)
– NotifConsumer (PSO feedback listener)
• PSO Optimizer (frameMQ.optimizers.PSO)
• Pub/Sub Broker (Kafka or MQTT) — external service
• Reader Agent (frameMQ.agent.reader.Reader)
• Reader Components
– FrameRetrieve (subscribe + reassemble chunks)
– FrameShow (decode + display)
• VideoSaver (optional) — common component to save to disk
• Models & Utils (parameter definitions, enums, helpers) — support classes
b. Relationships / Data flows
1. Client → Writer Agent: instantiates Writer(params)
2. Writer Agent → FrameCapture: pulls frames from camera
3. FrameCapture → FrameTransfer: encodes & chunks frames
4. FrameTransfer → Pub/Sub Broker: publishes on video-stream topic
5. (If PSO enabled) FrameTransfer → Broker Notification Topic
and NotifConsumer → PSO Optimizer → updates Writer parameters
6. Pub/Sub Broker → FrameRetrieve: Reader subscribes to video-stream
7. FrameRetrieve → FrameShow: reassemble + decode
8. FrameShow → Client: delivers frames (display, analysis)
9. VideoSaver can tap into any stage for persistence.
c. Architectural patterns / design principles
• Agent pattern: Reader/Writer agents encapsulate lifecycle (start(), stop())
• Strategy/Factory: support multiple protocols (Kafka vs MQTT) via parameterized classes
• Pub/Sub messaging: decoupled, asynchronous frame streaming
• Optional plugin architecture: new transports, encoders, optimizers drop into predefined interfaces
• Thread safety: internal use of thread-safe queues.
d. Key technologies / frameworks
• Pub/Sub: kafka-python, paho-mqtt
• Video: PyTurboJPEG, OpenCV (GStreamer)
• Optimization: custom PSO implementation in optimizers/PSO
• Python packaging: setuptools, pyproject.toml
Detailed capture of essential elements
• Notification topic and PSO feedback loop.
• Parameter flow: how Models (WriterParams, ReaderParams) configure each agent.
• Threading where necessary (e.g., concurrent capture+publish).