# mjpeg-streamer
## Overview
The mjpeg-streamer package provides a simple, flexible and efficient way to stream MJPEG video from OpenCV-compatible sources over HTTP. It provides a flexible interface that allows users to specify the video source and configure various parameters such as image size, quality, and FPS.
## Installation
You can install the package via pip:
```bash
pip install mjpeg-streamer
```
I would really recommend using `--prefer-binary`, especially with older versions of Python (e.g. 3.6). This will install pre-compiled binaries instead of building from source, which is much faster and less error-prone.
```bash
pip install mjpeg-streamer --prefer-binary
```
*Latest versions of dependencies (e.g. Numpy) don't always ship with pre-compiled binaries for older versions of Python, so this option installs the latest compatible version instead, even though it might be a bit older.*
## Usage
### Library
Here's a simple example that shows how to use the *mjpeg_streamer* package to stream video from a webcam:
```python
import cv2
from mjpeg_streamer import MjpegServer, Stream
cap = cv2.VideoCapture(0)
stream = Stream("my_camera", size=(640, 480), quality=50, fps=30)
server = MjpegServer("localhost", 8080)
server.add_stream(stream)
server.start()
while True:
_, frame = cap.read()
cv2.imshow(stream.name, frame)
if cv2.waitKey(1) == ord("q"):
break
stream.set_frame(frame)
server.stop()
cap.release()
cv2.destroyAllWindows()
```
This example starts the MJPEG server on ``localhost:8080`` and streams video from the webcam with the index of ``0``. The video is resized to 640x480 pixels, compressed with JPEG quality of 50, and streamed at 30 FPS.
To view the video stream, you can open a web browser and navigate to http://localhost:8080/my_camera.
To view the streams index, you can open a web browser and navigate to http://localhost:8080.
Don't forget to check out the [examples](examples) directory for more examples.
Check out the [class reference](#class-reference) for more details on the classes and methods provided by the package.
### Command Line Interface
The package also provides a simple command line interface that allows you to stream video from multiple sources using a single command. Here's an example that shows how to stream video from a webcam and a video file:
```bash
$ mjpeg-streamer -s 0 -s "video file.mp4" --prefix "ender 3 pro" --quality 75 --fps 24 --show-bandwidth
Streams index: http://localhost:8080
Available streams:
http://localhost:8080/ender_3_pro_0
http://localhost:8080/ender_3_pro_video_file_mp4
--------------------------------
Press Ctrl+C to stop the server
ender_3_pro_video_file_mp4: 599.28 KB/s | ender_3_pro_0: 824.44 KB/s
```
This command starts the MJPEG server on ``localhost:8080`` and streams video from the webcam with the index of ``0`` and the video file ``video file.mp4``. The streams are prefixed with ``ender 3 pro`` and compressed with JPEG quality of 75 and streamed at 24 FPS. The bandwidth of each stream is displayed in the console.
To view the video streams, you can open a web browser and navigate to the URLs displayed in the console.
Run ``mjpeg-streamer --help`` for more information on the available options.
***Note that*** the command line interface is limited and doesn't provide the same level of flexibility as the library. It's recommended to use the library if you need to customize the video streams or integrate them into your own application.
## Class Reference
### *Stream*
A class that represents a single video stream. A stream consists of a sequence of frames that can be set and retrieved using the set_frame and get_frame methods.
***Constructor:***
```python
Stream(name: str, size: Optional[Tuple[int, int]] = None, quality: int = 50, fps: int = 30)
```
Creates a new Stream instance with the given unique name, image size, JPEG quality (1-100), and FPS.
***Methods:***
- *set_frame*
```python
set_frame(frame: np.ndarray)
```
Sets the current frame to the given Numpy array (OpenCV frame).
<br>
- *get_bandwidth*
```python
get_bandwidth()
```
Returns the bandwidth of the stream in bytes per second.
*Tip: Divide the result by 1024 to get the bandwidth in kilobytes per second.*
<br>
- *get_frame*
```python
get_frame()
```
Returns the current frame as a Numpy array.
<br>
- *get_frame_processed*
```python
get_frame_processed()
```
Returns the current frame as a Numpy array after processing it with the specified image size and JPEG quality.
### *MjpegServer*
A class that represents an MJPEG server. The server can serve multiple video streams, each identified by a unique name.
***Constructor:***
```python
MjpegServer(host: str = "localhost", port: int = 8080)
```
Creates a new MjpegServer instance with the given host and port.
***Methods:***
- *add_stream*
```python
add_stream(stream: Stream)
```
Adds a new video stream to the server.
<br>
- *start*
```python
start()
```
Starts the server in a separate thread.
<br>
- *stop*
```python
stop()
```
Stops the server.
## Contributing
Contributions are welcome! Please open an issue or submit a pull request.
## License
This project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details.
***TL;DR: You can use, modify, and distribute this software for free or for profit, but you must make the source code available to your users and include a copy of [this license](LICENSE) in your project. Your modified work's license should also mention the original author and a link to this repository.***
Raw data
{
"_id": null,
"home_page": null,
"name": "mjpeg-streamer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "MJPEG,OpenCV,aiohttp,asyncio,computer-vision,multi-camera,server,streamer,streaming,video,webcam",
"author": null,
"author_email": "Ege Akman <me@egeakman.dev>",
"download_url": "https://files.pythonhosted.org/packages/c0/f2/b84145dd0b591a284484bab535f3c003c69650e32c58d8a76287d1502edb/mjpeg_streamer-2024.2.8.tar.gz",
"platform": null,
"description": "# mjpeg-streamer\n\n\n## Overview\n\nThe mjpeg-streamer package provides a simple, flexible and efficient way to stream MJPEG video from OpenCV-compatible sources over HTTP. It provides a flexible interface that allows users to specify the video source and configure various parameters such as image size, quality, and FPS.\n\n\n## Installation\n\nYou can install the package via pip:\n\n```bash\npip install mjpeg-streamer\n```\n\nI would really recommend using `--prefer-binary`, especially with older versions of Python (e.g. 3.6). This will install pre-compiled binaries instead of building from source, which is much faster and less error-prone.\n\n```bash\npip install mjpeg-streamer --prefer-binary\n```\n\n*Latest versions of dependencies (e.g. Numpy) don't always ship with pre-compiled binaries for older versions of Python, so this option installs the latest compatible version instead, even though it might be a bit older.*\n\n\n## Usage\n\n### Library\n\nHere's a simple example that shows how to use the *mjpeg_streamer* package to stream video from a webcam:\n\n```python\nimport cv2\nfrom mjpeg_streamer import MjpegServer, Stream\n\ncap = cv2.VideoCapture(0)\n\nstream = Stream(\"my_camera\", size=(640, 480), quality=50, fps=30)\n\nserver = MjpegServer(\"localhost\", 8080)\nserver.add_stream(stream)\nserver.start()\n\nwhile True:\n _, frame = cap.read()\n cv2.imshow(stream.name, frame)\n if cv2.waitKey(1) == ord(\"q\"):\n break\n\n stream.set_frame(frame)\n\nserver.stop()\ncap.release()\ncv2.destroyAllWindows()\n```\n\nThis example starts the MJPEG server on ``localhost:8080`` and streams video from the webcam with the index of ``0``. The video is resized to 640x480 pixels, compressed with JPEG quality of 50, and streamed at 30 FPS.\n\nTo view the video stream, you can open a web browser and navigate to http://localhost:8080/my_camera.\n\nTo view the streams index, you can open a web browser and navigate to http://localhost:8080.\n\nDon't forget to check out the [examples](examples) directory for more examples.\n\nCheck out the [class reference](#class-reference) for more details on the classes and methods provided by the package.\n\n### Command Line Interface\n\nThe package also provides a simple command line interface that allows you to stream video from multiple sources using a single command. Here's an example that shows how to stream video from a webcam and a video file:\n\n```bash\n$ mjpeg-streamer -s 0 -s \"video file.mp4\" --prefix \"ender 3 pro\" --quality 75 --fps 24 --show-bandwidth\n\nStreams index: http://localhost:8080\nAvailable streams:\n\nhttp://localhost:8080/ender_3_pro_0\nhttp://localhost:8080/ender_3_pro_video_file_mp4\n--------------------------------\n\n\nPress Ctrl+C to stop the server\n\nender_3_pro_video_file_mp4: 599.28 KB/s | ender_3_pro_0: 824.44 KB/s\n```\n\nThis command starts the MJPEG server on ``localhost:8080`` and streams video from the webcam with the index of ``0`` and the video file ``video file.mp4``. The streams are prefixed with ``ender 3 pro`` and compressed with JPEG quality of 75 and streamed at 24 FPS. The bandwidth of each stream is displayed in the console.\n\nTo view the video streams, you can open a web browser and navigate to the URLs displayed in the console.\n\nRun ``mjpeg-streamer --help`` for more information on the available options.\n\n***Note that*** the command line interface is limited and doesn't provide the same level of flexibility as the library. It's recommended to use the library if you need to customize the video streams or integrate them into your own application.\n\n\n## Class Reference\n\n### *Stream*\nA class that represents a single video stream. A stream consists of a sequence of frames that can be set and retrieved using the set_frame and get_frame methods.\n\n***Constructor:***\n\n```python\nStream(name: str, size: Optional[Tuple[int, int]] = None, quality: int = 50, fps: int = 30)\n```\n\nCreates a new Stream instance with the given unique name, image size, JPEG quality (1-100), and FPS.\n\n***Methods:***\n\n- *set_frame*\n\n ```python\n set_frame(frame: np.ndarray)\n ```\n\n Sets the current frame to the given Numpy array (OpenCV frame).\n\n<br>\n\n- *get_bandwidth*\n\n ```python\n get_bandwidth()\n ```\n\n Returns the bandwidth of the stream in bytes per second.\n *Tip: Divide the result by 1024 to get the bandwidth in kilobytes per second.*\n\n<br>\n\n- *get_frame*\n\n ```python\n get_frame()\n ```\n Returns the current frame as a Numpy array.\n\n<br>\n\n- *get_frame_processed*\n\n ```python\n get_frame_processed()\n ```\n\n Returns the current frame as a Numpy array after processing it with the specified image size and JPEG quality.\n\n### *MjpegServer*\n\nA class that represents an MJPEG server. The server can serve multiple video streams, each identified by a unique name.\n\n***Constructor:***\n\n```python\nMjpegServer(host: str = \"localhost\", port: int = 8080)\n```\n\nCreates a new MjpegServer instance with the given host and port.\n\n***Methods:***\n\n- *add_stream*\n\n ```python\n add_stream(stream: Stream)\n ```\n\n Adds a new video stream to the server.\n\n<br>\n\n- *start*\n\n ```python\n start()\n ```\n\n Starts the server in a separate thread.\n\n<br>\n\n- *stop*\n\n ```python\n stop()\n ```\n\n Stops the server.\n\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n\n## License\n\nThis project is licensed under the AGPL-3.0 License - see the [LICENSE](LICENSE) file for details.\n\n***TL;DR: You can use, modify, and distribute this software for free or for profit, but you must make the source code available to your users and include a copy of [this license](LICENSE) in your project. Your modified work's license should also mention the original author and a link to this repository.***\n",
"bugtrack_url": null,
"license": "AGPLv3",
"summary": "Simple, flexible and efficient MJPEG video streamer for Python",
"version": "2024.2.8",
"project_urls": {
"Homepage": "https://github.com/egeakman/mjpeg-streamer",
"Issues": "https://github.com/egeakman/mjpeg-streamer/issues",
"Releases": "https://github.com/egeakman/mjpeg-streamer/releases"
},
"split_keywords": [
"mjpeg",
"opencv",
"aiohttp",
"asyncio",
"computer-vision",
"multi-camera",
"server",
"streamer",
"streaming",
"video",
"webcam"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "71843d04da47ff73fed770390c0480a484077e0a1c0c6cc0149b9f4672c93f1f",
"md5": "3b2b8275482ef4102412ed7ac8b31250",
"sha256": "377265fd19539b7ac2332385ee7fec36eb337d620f583cdf8332bc5cca018163"
},
"downloads": -1,
"filename": "mjpeg_streamer-2024.2.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3b2b8275482ef4102412ed7ac8b31250",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 19462,
"upload_time": "2024-02-08T00:35:33",
"upload_time_iso_8601": "2024-02-08T00:35:33.573303Z",
"url": "https://files.pythonhosted.org/packages/71/84/3d04da47ff73fed770390c0480a484077e0a1c0c6cc0149b9f4672c93f1f/mjpeg_streamer-2024.2.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c0f2b84145dd0b591a284484bab535f3c003c69650e32c58d8a76287d1502edb",
"md5": "175d989d1395bde9e7316e64c626c161",
"sha256": "7fc4407501e79066b7ba67fb0b264743882d3ca4189d70b829a25cacc4e46923"
},
"downloads": -1,
"filename": "mjpeg_streamer-2024.2.8.tar.gz",
"has_sig": false,
"md5_digest": "175d989d1395bde9e7316e64c626c161",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 18919,
"upload_time": "2024-02-08T00:35:35",
"upload_time_iso_8601": "2024-02-08T00:35:35.643325Z",
"url": "https://files.pythonhosted.org/packages/c0/f2/b84145dd0b591a284484bab535f3c003c69650e32c58d8a76287d1502edb/mjpeg_streamer-2024.2.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-08 00:35:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "egeakman",
"github_project": "mjpeg-streamer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mjpeg-streamer"
}
JSON
