# actfw-gstreamer
actfw's components using GStreamer for implementation.
actfw is a framework for Actcast Application written in Python.
## Installation
```console
sudo apt-get update
sudo apt-get install -y python3-pip python3-pil
sudo apt-get install libgstreamer1.0-dev libgirepository1.0-dev ibgstreamer-plugins-base1.0-dev libglib2.0-dev
pip3 install actfw-gstreamer
```
## Document
- [API References](https://idein.github.io/actfw-gstreamer/latest/)
## Usage
See [actfw-core](https://github.com/Idein/actfw-core) for basic usage of `actfw` framework.
### Initalization
An application using `actfw-gstreamer` have to initialize GStreamer library before using `actfw-gstreamer`'s components.
```python
if __name__ == '__main__':
import gi
gi.require_version('Gst', '1.0')
from gi.repository import Gst
Gst.init(None)
main()
```
### `videotestsrc`
You can learn basic usage of `actfw-gstreamer` by using `videotestsrc`.
```python
from actfw_gstreamer.capture import GstreamerCapture
from actfw_gstreamer.gstreamer.converter import ConverterPIL
from actfw_gstreamer.gstreamer.stream import GstStreamBuilder
from actfw_gstreamer.restart_handler import SimpleRestartHandler
def videotestsrc_capture() -> GstreamerCapture:
pipeline_generator = preconfigured_pipeline.videotestsrc()
builder = GstStreamBuilder(pipeline_generator, ConverterPIL())
restart_handler = SimpleRestartHandler(10, 5)
return GstreamerCapture(builder, restart_handler)
def main():
app = actfw_core.Application()
capture = videotestsrc_capture()
app.register_task(capture)
consumer = YourConsumer()
app.register_task(consumer)
capture.connect(consumer)
app.run()
```
This generates [`Frame`](https://idein.github.io/actfw-core/latest/actfw_core.html#actfw_core.capture.Frame)s using [videotestsrc](https://gstreamer.freedesktop.org/documentation/videotestsrc/index.html).
- `GstreamerCapture` is a [`Producer`](https://idein.github.io/actfw-core/latest/actfw_core.task.html#actfw_core.task.producer.Producer).
- It generates `Frame`s consists of an output of `ConverterBase`. In this case, converter class is `ConverterPIL` and output is `PIL.Image.Image`.
- `GstStreamBuilder` and `PipelineGenerator` determines how to build gstreamer pipelines.
- `preconfigured_pipeline` provides preconfigured `PipelineGenerator`s.
- `SimpleRestartHandler` is a simple implementation of `RestartHandlerBase`, which determines "restart strategy".
For more details, see [tests](tests/intergation_test/test_gstreamer_output.py).
### `rtspsrc`
You can use [rtspsrc](https://gstreamer.freedesktop.org/documentation/rtsp/rtspsrc.html) using `preconfigured_pipeline.rtsp_h264()`.
Note that, as of now (2021-04), [Actcast application](https://actcast.io/docs/ForVendor/ApplicationDevelopment/) cannot use multicast UDP with dynamic address and unicast UDP.
(RTSP client communicates with RTSP server in RTP and determines adderss of mulitcast UDP.)
Therefore, you can use only the option `protocols = "tcp"`.
See also https://gstreamer.freedesktop.org/documentation/rtsp/rtspsrc.html#rtspsrc:protocols .
You should also pay attention to decoders. Available decoders are below:
| decoder (package) \ device | Raspberry Pi 3 | Raspberry Pi 4 | Jetson Nano |
| -------------------------------------------------------------- | -------------- | -------------- | ----------- |
| `omxh264` (from `gstreamer1.0-omx` and `gstreamer1.0-omx-rpi`) | o | x | ? |
| `v4l2h264dec` (from `gstreamer1.0-plugins-good`) | very slow | o | ? |
If your application supports various devices, you should branch by hardware types and select appropriate `decoder_type`.
For example, it is recommended to use `decoder_type` `omx` for Raspberry Pi 3 and `v4l2` for Raspberry Pi 4.
Currently, this library does not provide auto determination.
## Development Guide
### Installation of dev requirements
```console
pip3 install poetry
poetry install
```
### Running tests
```console
poetry run pytest -v
```
### Releasing package & API doc
CI will automatically do.
Follow the following branch/tag rules.
1. Make changes for next version in `master` branch (via pull-requests).
2. Make a PR that updates version in `pyproject.toml` and merge it to `master` branch.
3. Create GitHub release from `master` branch's HEAD.
1. [Draft a new release](https://github.com/Idein/actfw-gstreamer/releases/new).
2. Create new tag named `release-<New version>` (e.g. `release-1.4.0`) from `Choose a tag` pull down menu.
3. Write title and description.
4. Publish release.
4. Then CI will build/upload package to PyPI & API doc to GitHub Pages.
Raw data
{
"_id": null,
"home_page": "https://github.com/Idein/actfw-gstreamer",
"name": "actfw-gstreamer",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.7",
"maintainer_email": null,
"keywords": "actcast",
"author": "Idein Inc.",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/f3/0a/7561bd169dadfad18e0b95b87d422c9bf69d191299165d69f0e5957d9e51/actfw_gstreamer-0.4.0.tar.gz",
"platform": null,
"description": "# actfw-gstreamer\n\nactfw's components using GStreamer for implementation.\nactfw is a framework for Actcast Application written in Python.\n\n## Installation\n\n```console\nsudo apt-get update\nsudo apt-get install -y python3-pip python3-pil \nsudo apt-get install libgstreamer1.0-dev libgirepository1.0-dev ibgstreamer-plugins-base1.0-dev libglib2.0-dev\npip3 install actfw-gstreamer\n```\n\n## Document\n\n- [API References](https://idein.github.io/actfw-gstreamer/latest/)\n\n## Usage\n\nSee [actfw-core](https://github.com/Idein/actfw-core) for basic usage of `actfw` framework.\n\n### Initalization\n\nAn application using `actfw-gstreamer` have to initialize GStreamer library before using `actfw-gstreamer`'s components.\n\n```python\nif __name__ == '__main__':\n import gi\n\n gi.require_version('Gst', '1.0')\n from gi.repository import Gst\n Gst.init(None)\n\n main()\n```\n\n### `videotestsrc`\n\nYou can learn basic usage of `actfw-gstreamer` by using `videotestsrc`.\n\n```python\nfrom actfw_gstreamer.capture import GstreamerCapture\nfrom actfw_gstreamer.gstreamer.converter import ConverterPIL\nfrom actfw_gstreamer.gstreamer.stream import GstStreamBuilder\nfrom actfw_gstreamer.restart_handler import SimpleRestartHandler\n\n\ndef videotestsrc_capture() -> GstreamerCapture:\n pipeline_generator = preconfigured_pipeline.videotestsrc()\n builder = GstStreamBuilder(pipeline_generator, ConverterPIL())\n restart_handler = SimpleRestartHandler(10, 5)\n return GstreamerCapture(builder, restart_handler)\n\n\ndef main():\n app = actfw_core.Application()\n\n capture = videotestsrc_capture()\n app.register_task(capture)\n\n consumer = YourConsumer()\n app.register_task(consumer)\n\n capture.connect(consumer)\n\n app.run()\n```\n\nThis generates [`Frame`](https://idein.github.io/actfw-core/latest/actfw_core.html#actfw_core.capture.Frame)s using [videotestsrc](https://gstreamer.freedesktop.org/documentation/videotestsrc/index.html).\n\n- `GstreamerCapture` is a [`Producer`](https://idein.github.io/actfw-core/latest/actfw_core.task.html#actfw_core.task.producer.Producer).\n - It generates `Frame`s consists of an output of `ConverterBase`. In this case, converter class is `ConverterPIL` and output is `PIL.Image.Image`.\n- `GstStreamBuilder` and `PipelineGenerator` determines how to build gstreamer pipelines.\n- `preconfigured_pipeline` provides preconfigured `PipelineGenerator`s.\n- `SimpleRestartHandler` is a simple implementation of `RestartHandlerBase`, which determines \"restart strategy\".\n\nFor more details, see [tests](tests/intergation_test/test_gstreamer_output.py).\n\n### `rtspsrc`\n\nYou can use [rtspsrc](https://gstreamer.freedesktop.org/documentation/rtsp/rtspsrc.html) using `preconfigured_pipeline.rtsp_h264()`.\n\nNote that, as of now (2021-04), [Actcast application](https://actcast.io/docs/ForVendor/ApplicationDevelopment/) cannot use multicast UDP with dynamic address and unicast UDP.\n(RTSP client communicates with RTSP server in RTP and determines adderss of mulitcast UDP.)\nTherefore, you can use only the option `protocols = \"tcp\"`.\nSee also https://gstreamer.freedesktop.org/documentation/rtsp/rtspsrc.html#rtspsrc:protocols .\n\nYou should also pay attention to decoders. Available decoders are below:\n\n| decoder (package) \\ device | Raspberry Pi 3 | Raspberry Pi 4 | Jetson Nano |\n| -------------------------------------------------------------- | -------------- | -------------- | ----------- |\n| `omxh264` (from `gstreamer1.0-omx` and `gstreamer1.0-omx-rpi`) | o | x | ? |\n| `v4l2h264dec` (from `gstreamer1.0-plugins-good`) | very slow | o | ? |\n\nIf your application supports various devices, you should branch by hardware types and select appropriate `decoder_type`.\nFor example, it is recommended to use `decoder_type` `omx` for Raspberry Pi 3 and `v4l2` for Raspberry Pi 4.\nCurrently, this library does not provide auto determination.\n\n## Development Guide\n\n### Installation of dev requirements\n\n```console\npip3 install poetry\npoetry install\n```\n\n### Running tests\n\n```console\npoetry run pytest -v\n```\n\n### Releasing package & API doc\n\nCI will automatically do.\nFollow the following branch/tag rules.\n\n1. Make changes for next version in `master` branch (via pull-requests).\n2. Make a PR that updates version in `pyproject.toml` and merge it to `master` branch.\n3. Create GitHub release from `master` branch's HEAD.\n 1. [Draft a new release](https://github.com/Idein/actfw-gstreamer/releases/new).\n 2. Create new tag named `release-<New version>` (e.g. `release-1.4.0`) from `Choose a tag` pull down menu.\n 3. Write title and description.\n 4. Publish release.\n4. Then CI will build/upload package to PyPI & API doc to GitHub Pages.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "actfw's additional components using GStreamer",
"version": "0.4.0",
"project_urls": {
"Changelog": "https://github.com/Idein/actfw-gstreamer/blob/master/CHANGELOG.md",
"Documentation": "https://idein.github.io/actfw-gstreamer/latest/",
"Homepage": "https://github.com/Idein/actfw-gstreamer",
"Repository": "https://github.com/Idein/actfw-gstreamer"
},
"split_keywords": [
"actcast"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4c36d4813ef6f13d61003464b5986945be941632ae27875e6d40a3f571f3806d",
"md5": "c3c94b54c2505587f8eec89f101a470e",
"sha256": "31fa4508747e6285d787976002efb09dd6386904e6ec9a050f52c1ac083cf345"
},
"downloads": -1,
"filename": "actfw_gstreamer-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3c94b54c2505587f8eec89f101a470e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.7",
"size": 14556,
"upload_time": "2024-11-14T07:15:43",
"upload_time_iso_8601": "2024-11-14T07:15:43.486157Z",
"url": "https://files.pythonhosted.org/packages/4c/36/d4813ef6f13d61003464b5986945be941632ae27875e6d40a3f571f3806d/actfw_gstreamer-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f30a7561bd169dadfad18e0b95b87d422c9bf69d191299165d69f0e5957d9e51",
"md5": "0aecc9d7eeea901715879a236d4c6b07",
"sha256": "39fa60fd00351a27ae8f90e987edf671787f36eb6aa7867145c3fa9adeb69f3b"
},
"downloads": -1,
"filename": "actfw_gstreamer-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "0aecc9d7eeea901715879a236d4c6b07",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.7",
"size": 12718,
"upload_time": "2024-11-14T07:15:45",
"upload_time_iso_8601": "2024-11-14T07:15:45.083616Z",
"url": "https://files.pythonhosted.org/packages/f3/0a/7561bd169dadfad18e0b95b87d422c9bf69d191299165d69f0e5957d9e51/actfw_gstreamer-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-14 07:15:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Idein",
"github_project": "actfw-gstreamer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "actfw-gstreamer"
}
JSON
