{"id":27933325,"url":"https://github.com/groundlight/stream","last_synced_at":"2026-03-13T23:09:36.633Z","repository":{"id":149524581,"uuid":"495629337","full_name":"groundlight/stream","owner":"groundlight","description":"Groundlight Stream Processor - Container for analyzing video using RTSP etc","archived":false,"fork":false,"pushed_at":"2024-12-18T00:02:28.000Z","size":353,"stargazers_count":10,"open_issues_count":6,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-07T04:58:05.892Z","etag":null,"topics":["artificial-intelligence","computer-vision","machine-learning"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/groundlight/stream","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/groundlight.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-24T01:32:32.000Z","updated_at":"2024-11-22T15:57:31.000Z","dependencies_parsed_at":"2024-01-13T03:35:19.333Z","dependency_job_id":"959b866d-e6ac-485c-aa10-8f5a689ea69e","html_url":"https://github.com/groundlight/stream","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groundlight%2Fstream","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groundlight%2Fstream/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groundlight%2Fstream/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groundlight%2Fstream/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/groundlight","download_url":"https://codeload.github.com/groundlight/stream/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252816963,"owners_count":21808704,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","computer-vision","machine-learning"],"created_at":"2025-05-07T04:58:10.567Z","updated_at":"2026-03-13T23:09:33.338Z","avatar_url":"https://github.com/groundlight.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Groundlight Stream Processor\n\nA containerized python application that uses the [Groundlight](https://www.groundlight.ai/) [Python SDK](https://github.com/groundlight/python-sdk) to\nprocess frames from a video file, device, or stream.\n\n## Table of Contents\n- [Groundlight Stream Processor](#groundlight-stream-processor)\n  - [Table of Contents](#table-of-contents)\n  - [Download](#download)\n  - [Usage](#usage)\n  - [Examples](#examples)\n    - [Running with a Local MP4 File](#running-with-a-local-mp4-file)\n    - [Using a YouTube URL](#using-a-youtube-url)\n    - [Connecting an RTSP Stream](#connecting-an-rtsp-stream)\n  - [Further Reading](#further-reading)\n\n## Download\n\nThis application is easy to use on any system with Docker installed.\n\n```shell\n$ docker pull groundlight/stream\n```\n\n## Usage\n\nCommand line options are displayed like:\n\n``` shell\n$ docker run -it groundlight/stream -h\nusage: python -m stream -t TOKEN -d DETECTOR [options]\n\nGroundlight Stream Processor\n\nA command-line tool that captures frames from a video source and sends them to a Groundlight detector for analysis.\n\nSupports a variety of input sources including:\n- Video devices (webcams)\n- Video files (mp4, etc)\n- RTSP streams\n- YouTube videos\n- Image directories\n- Image URLs\n\noptions:\n  -h, --help            show this help message and exit\n  -t TOKEN, --token TOKEN\n                        Groundlight API token for authentication.\n  -d DETECTOR, --detector DETECTOR\n                        Detector ID to send ImageQueries to.\n  -e ENDPOINT, --endpoint ENDPOINT\n                        API endpoint to target. For example, could be pointed at an edge-endpoint proxy server (https://github.com/groundlight/edge-endpoint).\n  -s STREAM, --stream STREAM\n                        Video source. A device ID, filename, or URL. Defaults to device ID '0'.\n  -x {infer,device,directory,rtsp,youtube,file,image_url}, --streamtype {infer,device,directory,rtsp,youtube,file,image_url}\n                        Source type. Defaults to 'infer' which will attempt to set this value based on --stream.\n  -f FPS, --fps FPS     Frames per second to capture (0 for max rate). Defaults to 1 FPS.\n  -v, --verbose         Enable debug logging.\n  -m, --motion          Enables motion detection, which is disabled by default.\n  -r THRESHOLD, --threshold THRESHOLD\n                        Motion detection threshold (% pixels changed). Defaults to 1%.\n  -p POSTMOTION, --postmotion POSTMOTION\n                        Seconds to capture after motion detected. Defaults to 1 second.\n  -i MAXINTERVAL, --maxinterval MAXINTERVAL\n                        Max seconds between frames even without motion. Defaults to 1000 seconds.\n  -w RESIZE_WIDTH, --width RESIZE_WIDTH\n                        Resize width in pixels.\n  -y RESIZE_HEIGHT, --height RESIZE_HEIGHT\n                        Resize height in pixels.\n  -c CROP, --crop CROP  Crop region, specified as fractions (0-1) of each dimension (e.g. '0.25,0.2,0.8,0.9').\n```\n\nStart sending frames and getting predictions and labels using your own API token and detector ID:\n\n``` shell\ndocker run groundlight/stream \\\n    -t api_29imEXAMPLE \\\n    -d det_2MiD5Elu8bza7sil9l7KPpr694a \\\n    -s https://www.youtube.com/watch?v=210EXAMPLE \\\n    -f 1\n```\n\n## Examples\n### Running with a Local MP4 File\n\nTo process frames from a local MP4 file, you need to mount the file from your host machine into the Docker container. Here's how to do it:\n\n1. Place your MP4 file (e.g., `video.mp4`) in a directory on your host machine, such as `/path/to/video`.\n2. Run the Docker container, mounting the directory containing the video file:\n\n``` shell\ndocker run -v /path/to/video:/videos groundlight/stream \\\n    -t api_29imEXAMPLE \\\n    -d det_2MiD5Elu8bza7sil9l7KPpr694a \\\n    -s /videos/video.mp4 \\\n    -f 1\n```\n\nThis command mounts the `/path/to/video` directory on your host machine to the `/videos` directory inside the Docker container. The `-s` parameter is then set to the path of the MP4 file inside the container (`/videos/video.mp4`).\n\n### Using a YouTube URL\nYouTube URLs can be used to send frames to a detector by passing the video URL to the `-s` parameter:\n\n``` shell\n# Live Video from the International Space Station (Official NASA Stream)\nYOUTUBE_URL=\"https://www.youtube.com/watch?v=xAieE-QtOeM\"\n\ndocker run groundlight/stream \\\n    -t api_29imEXAMPLE \\\n    -d det_2MiD5Elu8bza7sil9l7KPpr694a \\\n    -s \"${YOUTUBE_URL}\" \\\n    -f 1\n```\n\nReplace `YOUTUBE_URL` with the url of the YouTube video you are interested in.\n\n### Connecting an RTSP Stream\n\nTo connect an RTSP stream from a camera or other source, you'll need the RTSP URL specific to your device. Check the instructions provided earlier in this document for obtaining the RTSP URL for your camera.\n\nOnce you have the RTSP URL, pass it to the `-s` parameter:\n\n``` shell\nRTSP_URL=\"rtsp://username:password@camera_ip_address:554/path/to/stream\"\n\ndocker run groundlight/stream \\\n    -t api_29imEXAMPLE \\\n    -d det_2MiD5Elu8bza7sil9l7KPpr694a \\\n    -s \"${RTSP_URL}\" \\\n    -f 1\n```\n\nReplace the RTSP URL with the one specific to your camera or streaming device.\n\n\n## Further Reading\n\n* [Camera types](CAMERAS.md) shows how to get RTSP stream URLs for many popular camera brands.\n* [Developing](DEVELOPING.md) discusses how this code is built and maintained.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroundlight%2Fstream","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroundlight%2Fstream","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroundlight%2Fstream/lists"}