| Name | bt-recover JSON |
| Version |
0.1.7
JSON |
| download |
| home_page | None |
| Summary | Download BrightTalk videos from m3u8 streams |
| upload_time | 2025-08-22 01:05:29 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
brighttalk
downloader
m3u8
video
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# BrightTalk-Recover
A Python command-line tool to download BrightTalk videos from m3u8 streams. This tool uses ffmpeg to efficiently download and process video streams.
## Features
- Download BrightTalk videos from m3u8 stream URLs
- Support for custom ffmpeg binary paths
- Progress bar for download tracking
- Dry-run mode to verify URLs before downloading
- Force mode to overwrite existing files
- Verbose logging options
- Docker support with multi-stage builds
- Environment variable support
## Requirements
- Python 3.10 or higher (tested on 3.10, 3.11, and 3.12)
- ffmpeg (runtime system requirement - not needed for installation)
### System Requirements
- Recommended OS: Ubuntu 24.04 LTS or newer
- Other Linux distributions, macOS, and Windows are also supported
### Installing ffmpeg
Note: ffmpeg is only needed when running the application, not for installing it.
#### macOS
```bash
brew install ffmpeg
```
#### Debian/Ubuntu
```bash
sudo apt update
sudo apt install ffmpeg
```
#### Windows
Download the ffmpeg binaries from [ffmpeg.org](https://ffmpeg.org/download.html) and add them to your system PATH.
## Installation
### For Users (Production)
```bash
# Install from PyPI
pip install bt-recover
# Or install from source (production dependencies only)
pip install -r requirements.txt
pip install .
```
### For Developers
```bash
# Clone the repository
git clone https://github.com/KevinOBytes/brighttalk-recover.git
cd brighttalk-recover
# Create and activate virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
pip install -r requirements-dev.txt
pip install -e .
# Install pre-commit hooks
pre-commit install
```
## Usage
### Basic Usage
```bash
bt-recover --url "https://cdn.brighttalk.com/ams/california/vod/video-screencast_932117.m3u8" --output "video.mp4"
```
### Using Environment Variables
```bash
export BT_URL="https://cdn.brighttalk.com/ams/california/vod/video-screencast_932117.m3u8"
export BT_OUTPUT="video.mp4"
bt-recover
```
### Command Line Options
```
--url URL The BrightTalk video URL (required if BT_URL not set)
--output FILE The output file name (required if BT_OUTPUT not set)
--dry-run Do not download, just verify the command
--force Overwrite existing output file
--verbose Enable verbose output
--quiet Minimize output
--debug Enable debug output
--ffmpeg PATH Custom path to ffmpeg binary
--version Show version number and exit
```
### Examples
Download with verbose output:
```bash
bt-recover --url "https://cdn.brighttalk.com/...m3u8" --output "video.mp4" --verbose
```
Use custom ffmpeg path:
```bash
bt-recover --url "https://cdn.brighttalk.com/...m3u8" --output "video.mp4" --ffmpeg "/opt/ffmpeg/bin/ffmpeg"
```
Dry run to verify URL:
```bash
bt-recover --url "https://cdn.brighttalk.com/...m3u8" --output "video.mp4" --dry-run
```
## Docker Usage
### Using Pre-built Image
```bash
docker pull ghcr.io/kevinobytes/bt-recover:latest
docker run --rm \
-v "$(pwd):/home/appuser/output" \
ghcr.io/kevinobytes/bt-recover:latest \
--url "https://cdn.brighttalk.com/...m3u8" \
--output "/home/appuser/output/video.mp4"
```
Latest image tags
- The `latest` tag is built automatically from the `main` branch by GitHub Actions.
- Release tags (e.g., `v1.2.3`) and commit `sha` tags are also pushed.
### Using Environment Variables with Docker
You can pass `BT_URL` and `BT_OUTPUT` instead of CLI flags:
```bash
export BT_URL="https://cdn.brighttalk.com/...m3u8"
export BT_OUTPUT="/home/appuser/output/video.mp4"
docker run --rm \
-v "$(pwd):/home/appuser/output" \
-e BT_URL -e BT_OUTPUT \
ghcr.io/kevinobytes/bt-recover:latest
```
### Building Locally
```bash
docker build -t bt-recover .
docker run --rm -v "$(pwd):/home/appuser/output" bt-recover \
--url "https://cdn.brighttalk.com/...m3u8" \
--output "/home/appuser/output/video.mp4"
```
### Using Docker Compose
```bash
# For production
docker-compose up
# For development
docker-compose -f docker-compose.dev.yml up
```
## Development
### Project Structure
```
brighttalk-recover/
├── LICENSE
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── pyproject.toml
├── requirements.txt # Production dependencies
├── requirements-dev.txt # Development dependencies
├── docker-compose.yml # Production Docker setup
├── docker-compose.dev.yml # Development Docker setup
├── Dockerfile
├── .pre-commit-config.yaml
├── src/
│ └── bt_recover/
│ ├── __init__.py
│ ├── __version__.py
│ ├── main.py
│ ├── cli.py # CLI handling
│ ├── config.py # Configuration management
│ ├── exceptions.py # Custom exceptions
│ ├── progress.py # Progress tracking
│ └── monitoring.py # Performance monitoring
└── tests/
├── conftest.py # Test fixtures
├── test_downloader.py # Unit tests
└── test_integration.py # Integration tests (require ffmpeg)
```
### Running Tests
```bash
# Run all tests
pytest
# Run with coverage report
pytest --cov=bt_recover
# Run with verbose output
pytest -v
# Run specific test file
pytest tests/test_downloader.py
# Run tests in Docker
docker-compose -f docker-compose.dev.yml up
```
### Code Quality Checks
```bash
# Run all pre-commit hooks
pre-commit run --all-files
# Run individual checks
black src/bt_recover tests # Code formatting
flake8 src/bt_recover tests # Style guide enforcement
mypy src/bt_recover # Type checking
# Run performance monitoring
python -m bt_recover.monitoring
```
### Dependencies
The project uses two requirements files:
- `requirements.txt`: Production dependencies needed to run the application
- `requirements-dev.txt`: Additional dependencies for development and testing
Key development dependencies include:
- pytest: Testing framework
- black: Code formatting
- flake8: Style guide enforcement
- mypy: Static type checking
- pre-commit: Git hooks management
- pytest-cov: Test coverage reporting
- tox: Test automation
### Configuration
The application currently supports:
1. Command line arguments
2. Environment variables
Note: A user config file (e.g., `~/.bt-recover.json`) is planned but not yet wired into the CLI. The example below shows the intended format:
```json
{
"ffmpeg_path": "/usr/local/bin/ffmpeg",
"output_dir": "~/videos",
"default_format": "mp4",
"timeout": 30,
"retry_attempts": 3
}
```
### Monitoring and Debugging
The application includes built-in monitoring tools:
- Progress bars for downloads
- Performance timing decorators
- Debug logging
- Error tracking
Enable debugging:
```bash
bt-recover --debug --verbose ...
```
### Docker Development
For development with Docker:
```bash
# Build and run tests
docker-compose -f docker-compose.dev.yml up
# Run specific tests
docker-compose -f docker-compose.dev.yml run bt-recover-dev pytest tests/test_downloader.py
# Run with mounted source code
docker-compose -f docker-compose.dev.yml run --rm -v .:/app bt-recover-dev
```
## Contributing
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for release history.
## Releasing
See [RELEASE.md](RELEASE.md) for the release process (version bump, push to main, tag to trigger PyPI and Docker publishes).
## Troubleshooting
### Common Issues
1. **ffmpeg not found**
- Ensure ffmpeg is installed and accessible in your system PATH
- Use the `--ffmpeg` option to specify a custom path
2. **Permission denied**
- Ensure you have write permissions in the output directory
- When using Docker, ensure the mounted volume has correct permissions
3. **Output file already exists**
- Use the `--force` flag to overwrite existing files
4. **Network issues**
- Check your internet connection
- Verify the m3u8 URL is accessible
- Try using `--debug` for more detailed error messages
## Support
- Open an issue on GitHub for bug reports or feature requests
- Check existing issues before creating a new one
- Include your OS, Python version, and bt-recover version when reporting issues
## Acknowledgments
- [ffmpeg](https://ffmpeg.org/) for video processing
- [ffmpeg-python](https://github.com/kkroening/ffmpeg-python) for Python bindings
- [tqdm](https://github.com/tqdm/tqdm) for progress bars
Raw data
{
"_id": null,
"home_page": null,
"name": "bt-recover",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "brighttalk, downloader, m3u8, video",
"author": null,
"author_email": "Kevin O'Connor <kevin@kevinbytes.com>",
"download_url": "https://files.pythonhosted.org/packages/57/d8/0ffe1141002064fef0585ae7ecc67508cf5dd56bb8f28f96e324686b1528/bt_recover-0.1.7.tar.gz",
"platform": null,
"description": "# BrightTalk-Recover\n\n\n\n\n\n\n\nA Python command-line tool to download BrightTalk videos from m3u8 streams. This tool uses ffmpeg to efficiently download and process video streams.\n\n## Features\n\n- Download BrightTalk videos from m3u8 stream URLs\n- Support for custom ffmpeg binary paths\n- Progress bar for download tracking\n- Dry-run mode to verify URLs before downloading\n- Force mode to overwrite existing files\n- Verbose logging options\n- Docker support with multi-stage builds\n- Environment variable support\n\n## Requirements\n\n- Python 3.10 or higher (tested on 3.10, 3.11, and 3.12)\n- ffmpeg (runtime system requirement - not needed for installation)\n\n### System Requirements\n\n- Recommended OS: Ubuntu 24.04 LTS or newer\n- Other Linux distributions, macOS, and Windows are also supported\n\n### Installing ffmpeg\n\nNote: ffmpeg is only needed when running the application, not for installing it.\n\n#### macOS\n```bash\nbrew install ffmpeg\n```\n\n#### Debian/Ubuntu\n```bash\nsudo apt update\nsudo apt install ffmpeg\n```\n\n#### Windows\nDownload the ffmpeg binaries from [ffmpeg.org](https://ffmpeg.org/download.html) and add them to your system PATH.\n\n## Installation\n\n### For Users (Production)\n```bash\n# Install from PyPI\npip install bt-recover\n\n# Or install from source (production dependencies only)\npip install -r requirements.txt\npip install .\n```\n\n### For Developers\n```bash\n# Clone the repository\ngit clone https://github.com/KevinOBytes/brighttalk-recover.git\ncd brighttalk-recover\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\npip install -e .\n\n# Install pre-commit hooks\npre-commit install\n```\n\n## Usage\n\n### Basic Usage\n```bash\nbt-recover --url \"https://cdn.brighttalk.com/ams/california/vod/video-screencast_932117.m3u8\" --output \"video.mp4\"\n```\n\n### Using Environment Variables\n```bash\nexport BT_URL=\"https://cdn.brighttalk.com/ams/california/vod/video-screencast_932117.m3u8\"\nexport BT_OUTPUT=\"video.mp4\"\nbt-recover\n```\n\n### Command Line Options\n\n```\n--url URL The BrightTalk video URL (required if BT_URL not set)\n--output FILE The output file name (required if BT_OUTPUT not set)\n--dry-run Do not download, just verify the command\n--force Overwrite existing output file\n--verbose Enable verbose output\n--quiet Minimize output\n--debug Enable debug output\n--ffmpeg PATH Custom path to ffmpeg binary\n--version Show version number and exit\n```\n\n### Examples\n\nDownload with verbose output:\n```bash\nbt-recover --url \"https://cdn.brighttalk.com/...m3u8\" --output \"video.mp4\" --verbose\n```\n\nUse custom ffmpeg path:\n```bash\nbt-recover --url \"https://cdn.brighttalk.com/...m3u8\" --output \"video.mp4\" --ffmpeg \"/opt/ffmpeg/bin/ffmpeg\"\n```\n\nDry run to verify URL:\n```bash\nbt-recover --url \"https://cdn.brighttalk.com/...m3u8\" --output \"video.mp4\" --dry-run\n```\n\n## Docker Usage\n\n### Using Pre-built Image\n```bash\ndocker pull ghcr.io/kevinobytes/bt-recover:latest\n\ndocker run --rm \\\n -v \"$(pwd):/home/appuser/output\" \\\n ghcr.io/kevinobytes/bt-recover:latest \\\n --url \"https://cdn.brighttalk.com/...m3u8\" \\\n --output \"/home/appuser/output/video.mp4\"\n```\n\nLatest image tags\n- The `latest` tag is built automatically from the `main` branch by GitHub Actions.\n- Release tags (e.g., `v1.2.3`) and commit `sha` tags are also pushed.\n\n### Using Environment Variables with Docker\nYou can pass `BT_URL` and `BT_OUTPUT` instead of CLI flags:\n```bash\nexport BT_URL=\"https://cdn.brighttalk.com/...m3u8\"\nexport BT_OUTPUT=\"/home/appuser/output/video.mp4\"\n\ndocker run --rm \\\n -v \"$(pwd):/home/appuser/output\" \\\n -e BT_URL -e BT_OUTPUT \\\n ghcr.io/kevinobytes/bt-recover:latest\n```\n### Building Locally\n\n```bash\ndocker build -t bt-recover .\n\ndocker run --rm -v \"$(pwd):/home/appuser/output\" bt-recover \\\n --url \"https://cdn.brighttalk.com/...m3u8\" \\\n --output \"/home/appuser/output/video.mp4\"\n```\n\n### Using Docker Compose\n```bash\n# For production\ndocker-compose up\n\n# For development\ndocker-compose -f docker-compose.dev.yml up\n```\n\n## Development\n\n### Project Structure\n```\nbrighttalk-recover/\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 CHANGELOG.md\n\u251c\u2500\u2500 CONTRIBUTING.md\n\u251c\u2500\u2500 pyproject.toml\n\u251c\u2500\u2500 requirements.txt # Production dependencies\n\u251c\u2500\u2500 requirements-dev.txt # Development dependencies\n\u251c\u2500\u2500 docker-compose.yml # Production Docker setup\n\u251c\u2500\u2500 docker-compose.dev.yml # Development Docker setup\n\u251c\u2500\u2500 Dockerfile\n\u251c\u2500\u2500 .pre-commit-config.yaml\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 bt_recover/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 __version__.py\n\u2502 \u251c\u2500\u2500 main.py\n\u2502 \u251c\u2500\u2500 cli.py # CLI handling\n\u2502 \u251c\u2500\u2500 config.py # Configuration management\n\u2502 \u251c\u2500\u2500 exceptions.py # Custom exceptions\n\u2502 \u251c\u2500\u2500 progress.py # Progress tracking\n\u2502 \u2514\u2500\u2500 monitoring.py # Performance monitoring\n\u2514\u2500\u2500 tests/\n \u251c\u2500\u2500 conftest.py # Test fixtures\n \u251c\u2500\u2500 test_downloader.py # Unit tests\n \u2514\u2500\u2500 test_integration.py # Integration tests (require ffmpeg)\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage report\npytest --cov=bt_recover\n\n# Run with verbose output\npytest -v\n\n# Run specific test file\npytest tests/test_downloader.py\n\n# Run tests in Docker\ndocker-compose -f docker-compose.dev.yml up\n```\n\n### Code Quality Checks\n\n```bash\n# Run all pre-commit hooks\npre-commit run --all-files\n\n# Run individual checks\nblack src/bt_recover tests # Code formatting\nflake8 src/bt_recover tests # Style guide enforcement\nmypy src/bt_recover # Type checking\n\n# Run performance monitoring\npython -m bt_recover.monitoring\n```\n\n### Dependencies\n\nThe project uses two requirements files:\n- `requirements.txt`: Production dependencies needed to run the application\n- `requirements-dev.txt`: Additional dependencies for development and testing\n\nKey development dependencies include:\n- pytest: Testing framework\n- black: Code formatting\n- flake8: Style guide enforcement\n- mypy: Static type checking\n- pre-commit: Git hooks management\n- pytest-cov: Test coverage reporting\n- tox: Test automation\n\n### Configuration\n\nThe application currently supports:\n1. Command line arguments\n2. Environment variables\n\nNote: A user config file (e.g., `~/.bt-recover.json`) is planned but not yet wired into the CLI. The example below shows the intended format:\n```json\n{\n \"ffmpeg_path\": \"/usr/local/bin/ffmpeg\",\n \"output_dir\": \"~/videos\",\n \"default_format\": \"mp4\",\n \"timeout\": 30,\n \"retry_attempts\": 3\n}\n```\n\n### Monitoring and Debugging\n\nThe application includes built-in monitoring tools:\n- Progress bars for downloads\n- Performance timing decorators\n- Debug logging\n- Error tracking\n\nEnable debugging:\n```bash\nbt-recover --debug --verbose ...\n```\n\n### Docker Development\n\nFor development with Docker:\n\n```bash\n# Build and run tests\ndocker-compose -f docker-compose.dev.yml up\n\n# Run specific tests\ndocker-compose -f docker-compose.dev.yml run bt-recover-dev pytest tests/test_downloader.py\n\n# Run with mounted source code\ndocker-compose -f docker-compose.dev.yml run --rm -v .:/app bt-recover-dev\n```\n\n## Contributing\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history.\n\n## Releasing\n\nSee [RELEASE.md](RELEASE.md) for the release process (version bump, push to main, tag to trigger PyPI and Docker publishes).\n\n## Troubleshooting\n\n### Common Issues\n\n1. **ffmpeg not found**\n - Ensure ffmpeg is installed and accessible in your system PATH\n - Use the `--ffmpeg` option to specify a custom path\n\n2. **Permission denied**\n - Ensure you have write permissions in the output directory\n - When using Docker, ensure the mounted volume has correct permissions\n\n3. **Output file already exists**\n - Use the `--force` flag to overwrite existing files\n\n4. **Network issues**\n - Check your internet connection\n - Verify the m3u8 URL is accessible\n - Try using `--debug` for more detailed error messages\n\n## Support\n\n- Open an issue on GitHub for bug reports or feature requests\n- Check existing issues before creating a new one\n- Include your OS, Python version, and bt-recover version when reporting issues\n\n## Acknowledgments\n\n- [ffmpeg](https://ffmpeg.org/) for video processing\n- [ffmpeg-python](https://github.com/kkroening/ffmpeg-python) for Python bindings\n- [tqdm](https://github.com/tqdm/tqdm) for progress bars\n",
"bugtrack_url": null,
"license": null,
"summary": "Download BrightTalk videos from m3u8 streams",
"version": "0.1.7",
"project_urls": {
"Documentation": "https://github.com/KevinOBytes/bt-recover#readme",
"Homepage": "https://github.com/KevinOBytes/bt-recover",
"Issues": "https://github.com/KevinOBytes/bt-recover/issues"
},
"split_keywords": [
"brighttalk",
" downloader",
" m3u8",
" video"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c83d3777a73bbc87be14b0ff1fca48baf6fb42f487ba7949758031b3eaaec238",
"md5": "ca43e8f6bd681f6680bd079cf9e2e051",
"sha256": "495bd951e221e4c6c1c7d39b916e8b90c14c9580919243e1ca0f3b347356e03e"
},
"downloads": -1,
"filename": "bt_recover-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca43e8f6bd681f6680bd079cf9e2e051",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 10909,
"upload_time": "2025-08-22T01:05:27",
"upload_time_iso_8601": "2025-08-22T01:05:27.909762Z",
"url": "https://files.pythonhosted.org/packages/c8/3d/3777a73bbc87be14b0ff1fca48baf6fb42f487ba7949758031b3eaaec238/bt_recover-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "57d80ffe1141002064fef0585ae7ecc67508cf5dd56bb8f28f96e324686b1528",
"md5": "c0719f0484afacbcb1c5ac6cdcd2102d",
"sha256": "b4cce9a863a1a47ea5eb72ccbdb0142b75126679f37af6a90174832a9c83341f"
},
"downloads": -1,
"filename": "bt_recover-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "c0719f0484afacbcb1c5ac6cdcd2102d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 18697,
"upload_time": "2025-08-22T01:05:29",
"upload_time_iso_8601": "2025-08-22T01:05:29.013425Z",
"url": "https://files.pythonhosted.org/packages/57/d8/0ffe1141002064fef0585ae7ecc67508cf5dd56bb8f28f96e324686b1528/bt_recover-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-22 01:05:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KevinOBytes",
"github_project": "bt-recover#readme",
"github_not_found": true,
"lcname": "bt-recover"
}
