{"id":42085934,"url":"https://github.com/themactep/streamripper","last_synced_at":"2026-01-26T10:18:24.372Z","repository":{"id":321815829,"uuid":"1087236216","full_name":"themactep/streamripper","owner":"themactep","description":"RTSP stream analyzer and video quality assessment tool","archived":false,"fork":false,"pushed_at":"2025-10-31T17:19:36.000Z","size":42,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-31T18:23:12.925Z","etag":null,"topics":["rtsp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/themactep.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-31T15:26:33.000Z","updated_at":"2025-10-31T17:19:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/themactep/streamripper","commit_stats":null,"previous_names":["themactep/streamripper"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/themactep/streamripper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themactep%2Fstreamripper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themactep%2Fstreamripper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themactep%2Fstreamripper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themactep%2Fstreamripper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/themactep","download_url":"https://codeload.github.com/themactep/streamripper/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/themactep%2Fstreamripper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28774301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T09:42:00.929Z","status":"ssl_error","status_checked_at":"2026-01-26T09:42:00.591Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["rtsp"],"created_at":"2026-01-26T10:18:23.523Z","updated_at":"2026-01-26T10:18:24.365Z","avatar_url":"https://github.com/themactep.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Streamripper\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n\nStreamripper is a powerful RTSP stream analyzer and video quality assessment tool. It provides comprehensive analysis of video streams, including frame analysis, timing drift detection, and visual reporting capabilities.\n\n## Features\n\n- **RTSP Stream Analysis**: Analyze live RTSP video streams in real-time\n- **Frame Type Detection**: Identify I-frames, P-frames, and B-frames\n- **Quality Metrics**: Calculate frame sizes, timing drift, and stream statistics\n- **Visual Reports**: Generate comprehensive charts and graphs\n- **CSV Export**: Export analysis data for further processing\n- **Flexible Duration**: Analyze streams for custom time periods\n- **Debug Logging**: Detailed logging for troubleshooting\n\n## Installation\n\n### Prerequisites\n\n- Python 3.8 or higher\n- FFmpeg libraries (for av package)\n\n#### Installing FFmpeg\n\n**Ubuntu/Debian:**\n```bash\nsudo apt update\nsudo apt install ffmpeg libavformat-dev libavcodec-dev libavdevice-dev libavutil-dev libswscale-dev libswresample-dev\n```\n\n**macOS:**\n```bash\nbrew install ffmpeg\n```\n\n**Windows:**\nDownload FFmpeg from [https://ffmpeg.org/download.html](https://ffmpeg.org/download.html)\n\n### Recommended Installation (using uv)\n\n[uv](https://docs.astral.sh/uv/) is the fastest Python package manager and provides excellent virtual environment management. It's the recommended way to install and work with Streamripper.\n\n#### Install uv (if not already installed)\n\n```bash\n# On macOS and Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# On Windows\npowershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# Or using pip\npip install uv\n```\n\n#### Basic Installation\n\n```bash\ngit clone https://github.com/themactep/streamripper.git\ncd streamripper\n\n# Create virtual environment and install package\nuv venv\nuv pip install -e .\n```\n\n#### Development Installation\n\n```bash\ngit clone https://github.com/themactep/streamripper.git\ncd streamripper\n\n# Create virtual environment and install with development dependencies\nuv venv\nuv pip install -e \".[dev]\"\n```\n\n#### Activate the virtual environment\n\n```bash\n# On Linux/macOS\nsource .venv/bin/activate\n\n# On Windows\n.venv\\Scripts\\activate\n```\n\n### Alternative Installation Methods\n\n#### Using pip with venv\n\n```bash\ngit clone https://github.com/themactep/streamripper.git\ncd streamripper\n\n# Create and activate virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install package\npip install -e .\n\n# For development\npip install -e \".[dev]\"\n```\n\n#### Using conda\n\n```bash\ngit clone https://github.com/themactep/streamripper.git\ncd streamripper\n\n# Create and activate conda environment\nconda create -n streamripper python=3.8\nconda activate streamripper\n\n# Install package\npip install -e .\n```\n\n#### Direct pip installation (not recommended for development)\n\n```bash\ngit clone https://github.com/themactep/streamripper.git\ncd streamripper\npip install -e .\n```\n\n## Usage\n\n### Command Line Interface\n\n```bash\n# Full analysis (stream, debug log, forensic, and chart by default)\nstreamripper rtsp://example.com/stream\n\n# Analyze for 60 seconds instead of default 30\nstreamripper rtsp://example.com/stream --duration 60\n\n# Minimal output (only chart and report)\nstreamripper rtsp://example.com/stream --no-save-stream --no-debug-log --no-forensic\n\n# Skip stream saving but keep debug log and forensic\nstreamripper rtsp://example.com/stream --no-save-stream\n\n# Skip forensic corruption detection\nstreamripper rtsp://example.com/stream --no-forensic\n\n# Skip chart generation but keep stream, debug log, and forensic\nstreamripper rtsp://example.com/stream --no-chart\n\n# Custom output directory\nstreamripper rtsp://example.com/stream --output-dir ./my_analysis\n\n# Generate separate charts for audio and video\nstreamripper rtsp://example.com/stream --chart-type separate\n\n# Generate only video chart\nstreamripper rtsp://example.com/stream --chart-type video-only\n\n# Generate comprehensive chart with all packets and separate drift lines\nstreamripper rtsp://example.com/stream --chart-type comprehensive\n```\n\n### Python API\n\n```python\nfrom streamripper import analyze_rtsp_stream, generate_combined_chart\n\n# Analyze a stream\ndata = analyze_rtsp_stream(\n    rtsp_url=\"rtsp://example.com/stream\",\n    duration=60,\n    output_dir=\"./output\",\n    debug_log=True,\n    timestamp_prefix=\"analysis\",\n    save_stream=True  # Save raw stream for further analysis\n)\n\n# Generate combined visualization showing both audio and video time drifts\ngenerate_combined_chart(\n    output_dir=\"./output\",\n    data=data,\n    timestamp_prefix=\"analysis\"\n)\n```\n\n## Output\n\nStreamripper generates several types of output:\n\n1. **CSV Data File**: Detailed frame-by-frame analysis data\n2. **Visual Charts**: PNG images with frame sizes and timing drift plots\n   - **Combined Chart**: Shows both audio and video time drifts on the same plot (default)\n   - **Comprehensive Chart**: Two-panel view with all packets (top) and separate drift lines (bottom)\n   - **Separate Charts**: Individual charts for video and audio analysis\n   - **Video-only Chart**: Focus on video stream analysis\n   - **Audio-only Chart**: Focus on audio stream analysis\n3. **Console Report**: Summary statistics and analysis results\n4. **Debug Logs**: Detailed logging information (when enabled)\n5. **Raw Bitstream File**: Unaltered H.264/H.265 bitstream (when `--save-stream` is used)\n\n### Organized Output Structure\n\nStreamripper automatically organizes outputs by stream source and run timestamp:\n\n```\noutput/\n└── 192_168_88_33_ch0/               # Sanitized URL directory (no protocol)\n    └── 20231031_143022/             # Timestamp directory for this run\n        ├── report.txt\n        ├── flow.csv                 # Debug flow data (when --debug-log used)\n        ├── chart_combined.png       # Analysis chart\n        ├── stream.h264              # Raw H.264 bitstream (when --save-stream used)\n        └── corruption.txt           # Corruption details (when --forensic used)\n└── camera_example_com_554_stream/   # Another stream\n    └── 20231031_150000/\n        ├── report.txt\n        ├── chart_combined.png\n        └── stream.h265              # Raw H.265 bitstream\n```\n\n**Directory Naming:**\n- Credentials are automatically removed from URLs\n- Protocol prefix (rtsp://) is removed\n- Non-alphanumeric characters become underscores\n- `rtsp://user:pass@192.168.88.33/ch0` → `192_168_88_33_ch0/`\n- `rtsp://camera.example.com:554/stream` → `camera_example_com_554_stream/`\n- Each run creates a timestamped subdirectory for clean organization\n\n## Configuration\n\n### Environment Variables\n\n- `STREAMRIPPER_OUTPUT_DIR`: Default output directory\n- `STREAMRIPPER_DEBUG`: Enable debug logging by default\n\n### Command Line Options\n\n- `--duration`: Analysis duration in seconds (default: 30)\n- `--output-dir`: Output directory for results (default: ./output)\n- `--no-debug-log`: Disable debug flow logging (enabled by default)\n- `--no-save-stream`: Disable raw bitstream saving (enabled by default)\n- `--no-forensic`: Disable forensic corruption detection (enabled by default)\n- `--timestamp-prefix`: Custom prefix for output files\n- `--chart-type`: Type of chart to generate (combined, comprehensive, separate, video-only, audio-only) (default: combined)\n- `--no-chart`: Skip chart generation entirely\n\n## Development\n\n### Setting up Development Environment\n\n#### Recommended: Using uv\n\n```bash\ngit clone https://github.com/themactep/streamripper.git\ncd streamripper\n\n# Create virtual environment and install development dependencies\nuv venv\nuv pip install -e \".[dev]\"\n\n# Activate virtual environment\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install pre-commit hooks\npre-commit install\n```\n\n#### Alternative: Using pip\n\n```bash\ngit clone https://github.com/themactep/streamripper.git\ncd streamripper\n\n# Create and activate virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install development dependencies\npip install -r requirements-dev.txt\npre-commit install\n```\n\n### Running Tests\n\n```bash\n# Make sure your virtual environment is activated\npytest\n```\n\n### Code Formatting\n\n```bash\n# Make sure your virtual environment is activated\nblack src/ tests/\nflake8 src/ tests/\nmypy src/\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [PyAV](https://github.com/PyAV-Org/PyAV) for video processing\n- Uses [matplotlib](https://matplotlib.org/) for visualization\n- Data analysis powered by [pandas](https://pandas.pydata.org/)\n\n## Support\n\nFor support, please open an issue on GitHub or contact the maintainer at paul@themactep.com.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthemactep%2Fstreamripper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthemactep%2Fstreamripper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthemactep%2Fstreamripper/lists"}