This section contains the full installation guide.

• NAS/Server: 2GB+ RAM, 2+ CPU cores, Docker support
• Client: Chrome browser (v88+)

• Docker 20.10+
• Docker Compose 2.0+
• Network connectivity between Chrome and NAS

You will do 3 things:

1. Deploy the backend on your NAS/server (pick Synology or Non-Synology)
2. Install + configure the Chrome extension
3. Verify it works

DB_PASSWORD=your_secure_password_here
API_KEY=your_api_key_minimum_32_chars
MAX_DOWNLOAD_WORKERS=20
MAX_RETRY_ATTEMPTS=3
FFMPEG_THREADS=2
LOG_LEVEL=INFO
ALLOWED_ORIGINS=chrome-extension://*
CORS_ALLOW_CREDENTIALS=false
RATE_LIMIT_PER_MINUTE=10
ALLOWED_CLIENT_CIDRS=
SSRF_GUARD=false

wget https://github.com/asdfghj1237890/WebVideo2NAS/releases/latest/download/WebVideo2NAS-downloader-docker.zip
mkdir -p docker
cd docker
unzip ../WebVideo2NAS-downloader-docker.zip
cd video-downloader/docker
mkdir -p ../logs ../downloads/completed

API_KEY=$(openssl rand -base64 32)
DB_PASSWORD=$(openssl rand -base64 24)

## If you don't have openssl, set API_KEY/DB_PASSWORD manually (any strong random strings)
cat > .env << EOF
DB_PASSWORD=${DB_PASSWORD}
API_KEY=${API_KEY}
MAX_DOWNLOAD_WORKERS=20
MAX_RETRY_ATTEMPTS=3
FFMPEG_THREADS=2
LOG_LEVEL=INFO
ALLOWED_ORIGINS=chrome-extension://*
CORS_ALLOW_CREDENTIALS=false
RATE_LIMIT_PER_MINUTE=10
ALLOWED_CLIENT_CIDRS=
SSRF_GUARD=false
EOF

echo "Your API Key: ${API_KEY}"

docker-compose up -d
curl http://localhost:52052/api/health

1. Open chrome://extensions/
2. Enable Developer mode
3. Click Load unpacked
4. Select the chrome-extension folder
5. Open extension Settings:
   • NAS Endpoint: http://YOUR_NAS_IP:52052 (use your NAS/server LAN IP; not localhost)
   • API Key: your API_KEY from .env
6. Click Test Connection → should show connected

• Usage: see Usage
• Troubleshooting: see Troubleshooting
• Configuration: see Configuration

Currently, the following versions are being supported with security updates:

If you discover a security vulnerability within WebVideo2NAS, please follow these steps:

• Do not open a public GitHub issue
• Do not disclose the vulnerability publicly until it has been addressed

1. Email the maintainers privately (create a security advisory on GitHub)
2. Provide detailed information about the vulnerability:
   • Type of issue (e.g., authentication bypass, SQL injection, XSS)
   • Full paths of affected source files
   • Location of the affected code (tag/branch/commit)
   • Step-by-step instructions to reproduce the issue
   • Proof-of-concept or exploit code (if possible)
   • Impact of the vulnerability

• Acknowledgment: Within 48 hours
• Initial Assessment: Within 5 business days
• Status Update: Every 7 days until resolved
• Fix Release: Depends on severity (Critical: 7 days, High: 14 days, Medium: 30 days)

1. API Key Security

   • Generate strong API keys (minimum 32 characters)
   • Use openssl rand -base64 32 to generate secure keys
   • Never commit .env files to version control
   • Rotate API keys periodically

2. Network Security

   • Use HTTPS in production (not HTTP)
   • Configure proper firewall rules
   • Limit API access to trusted networks
   • Consider using VPN or Tailscale for remote access

3. Docker Security

   • Keep Docker images updated
   • Run containers as non-root users when possible
   • Limit container capabilities
   • Use Docker secrets for sensitive data

4. Database Security

   • Use strong database passwords
   • Restrict database access to localhost
   • Regular database backups
   • Enable PostgreSQL SSL connections in production

1. Code Security

   • Validate all user inputs
   • Use parameterized queries (already implemented)
   • Sanitize file paths
   • Implement rate limiting (already implemented)

2. Dependency Security

   • Regularly update dependencies
   • Use pip audit to check for vulnerable packages
   • Review dependencies before adding new ones

3. Testing

   • Test with various malicious inputs
   • Check for path traversal vulnerabilities
   • Verify authentication on all endpoints
   • Test CORS configuration

1. Authentication: API Key-based (Bearer token)

   • Simple but effective for private NAS deployments
   • Consider OAuth2 for multi-user scenarios

2. CORS: Configured for Chrome extensions

   • Default: chrome-extension://*
   • Adjust for your specific needs

3. Rate Limiting: Basic implementation

   • Default: 10 requests per minute
   • Configurable via environment variables

4. File System Access:

   • Limited to configured download directories
   • No user-provided file paths accepted

1. DRM Content: This tool cannot and should not be used to bypass DRM
2. Copyright: Users are responsible for ensuring legal rights to download content
3. Public Exposure: Not designed for public internet exposure without additional security layers

# Strong credentials
API_KEY=$(openssl rand -base64 32)
DB_PASSWORD=$(openssl rand -base64 24)

# Network restrictions
ALLOWED_ORIGINS=chrome-extension://your-extension-id

# Monitoring
LOG_LEVEL=INFO

Before deploying to production:

• Change default passwords
• Generate strong API keys
• Configure HTTPS with valid certificate
• Set up firewall rules
• Enable rate limiting
• Configure proper CORS
• Review and restrict file system access
• Set up log monitoring
• Regular security updates
• Backup strategy in place

For security concerns, please use GitHub Security Advisories feature or contact the maintainers directly.

Last Updated: 2025-12-12

1. Read the Documentation

   • README.md - Project overview
   • docs/SPECIFICATION.md - Technical specification
   • docs/ARCHITECTURE.md - System architecture

2. Set Up Development Environment

   • Docker & Docker Compose
   • Python 3.11+
   • Chrome browser with Developer mode
   • Code editor of your choice

git clone https://github.com/yourusername/webvideo2nas.git
cd webvideo2nas

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

• Follow existing code style
• Write clear, descriptive commit messages
• Keep commits focused and atomic
• Add tests for new features
• Update documentation as needed

Backend (Docker Services):

cd video-downloader/docker
docker-compose up --build
# Test API endpoints
./test-api.sh

Chrome Extension:

cd chrome-extension
# Load unpacked extension in Chrome
# Test functionality manually

• Push your branch to your fork
• Create a pull request to the main repository
• Describe your changes clearly
• Reference any related issues

• Follow PEP 8
• Use type hints where appropriate
• Keep functions focused and small
• Add docstrings for classes and public methods

Example:

def download_segment(url: str, timeout: int = 30) -> bytes:
    """
    Download a single HLS segment.
    
    Args:
        url: The segment URL
        timeout: Request timeout in seconds
        
    Returns:
        The segment content as bytes
        
    Raises:
        DownloadError: If download fails
    """
    pass

• Use ES6+ features
• Use const and let, avoid var
• Use async/await for asynchronous operations
• Keep functions focused and small

Example:

async function detectM3u8Urls(details) {
  const url = details.url.toLowerCase();
  if (url.includes('.m3u8')) {
    await notifyUrlDetected(details.url);
  }
}

WebVideo2NAS/
├── chrome-extension/      # Chrome extension source
│   ├── background.js      # Background service worker
│   ├── sidepanel.*        # Extension side panel UI
│   ├── options/           # Extension options page
│   ├── icons/             # Extension icons
│   └── manifest.json      # Extension manifest
├── video-downloader/      # NAS downloader
│   └── docker/            # Docker services
│       ├── api/           # FastAPI service
│       ├── worker/        # Download worker
│       ├── docker-compose.yml
│       ├── docker-compose.synology.yml
│       └── init-db.sql
├── docs/                  # Architecture/specs/docs
└── pics/                  # Diagrams

• M3U8 parser improvements
• FFmpeg integration enhancements
• Chrome extension features
• Bug fixes
• Performance optimizations
• Documentation improvements

• Unit tests
• Integration tests
• Error handling improvements
• Logging enhancements
• UI/UX improvements

• Additional NAS platform support
• Advanced retry strategies
• Download resume capability
• Bandwidth throttling
• Scheduled downloads

When reporting issues, please include:

• Clear description of the problem
• Steps to reproduce
• Expected behavior
• Actual behavior
• Environment details (OS, Docker version, NAS model, etc.)
• Relevant logs or error messages

1. Maintainers will review your pull request
2. Address any feedback or requested changes
3. Once approved, your PR will be merged
4. Your contribution will be acknowledged in release notes

• Check existing issues and discussions
• Read the documentation thoroughly
• Ask questions in GitHub Discussions

By contributing, you agree that your contributions will be licensed under the MIT License.

• Add GitHub Actions CI workflow for Python unit tests (API + worker via uv), Chrome extension unit tests (Vitest), and an API smoke test using Docker Compose
• Add unit tests for Chrome extension helpers and downloader worker/API edge cases

• Exclude tests, node_modules, and Python caches from release zip artifacts

• Fix side panel quality extraction so adjacent quality markers (e.g. 720p_1080p) are detected reliably
• Make M3U8 parsing more robust: handle Accept-Encoding: br case-insensitively and ignore invalid AES-128 IV values

• Update API specification to remove /api/auth/validate endpoint

• Improve video URL detection and Chrome extension UI behavior
• Update deployment instructions and Docker Compose configuration for the downloader stack
• Rename downloader directory from m3u8-downloader/ to video-downloader/ and update related configuration references
• Bump project version to 1.8.4 across Chrome extension, API, worker, and docs

• Update installation/examples to use video-downloader/ and video_* container names (remove legacy m3u8-*)

• Add db_cleanup service to prune finished jobs (keep latest 100) on an interval via CLEANUP_INTERVAL_SECONDS

• Align Docker Compose names and database to video_* / video_db for both standard and Synology deployments

• Update Project Structure tree to match repository layout
• Document CLEANUP_INTERVAL_SECONDS in .env.example

• Side panel now picks up updated NAS settings without getting stuck, and shows a more specific connection error reason
• GitHub release workflow updated to use the renamed video-downloader/ directory

• Documentation updates

• User settings for auto-detection and notifications
• SSRF protection and client IP allowlisting in API and worker

• Remove MAX_CONCURRENT_DOWNLOADS configuration and update related documentation
• Update environment variables and Docker Compose settings to reflect worker configuration changes

• Internationalization (i18n) support for side panel and options

• Rename project from "Chrome2NAS M3U8 Downloader" to "WebVideo2NAS"
• Improve video URL detection, handling, and deduplication in the background script

• Improve side panel UI and error handling; enhance job status display and duration formatting
• Improve media duration handling in the download worker
• Improve header normalization and M3U8 request handling across extension background and worker
• Enhance downloader encryption handling and session management
• Documentation updates (port usage/spec details) and version display updates

• Brotli support and header sanitization in the M3U8 parser
• Cooperative cancellation support in SegmentDownloader

• Sidepanel click handling for job actions (use currentTarget)

• Improve M3U8 validation and error handling in the worker
• Chrome extension UI/theming refinements and progress text rendering updates
• Release workflow updated to generate changelog and bump version to 1.5.0

• Implement enhanced header capturing and Referer strategies in the downloader

• Improve error handling and anti-hotlinking protections in downloader/parser modules

• AES-128 decryption support for encrypted HLS segments
• Download cancellation support with UI status labels and backend handling
• MP4 downloads alongside M3U8

• Legacy SSL support for downloader/parser modules

• Expanded to 2 download workers for parallel processing capability
  • Total system capacity increased to 2 concurrent videos (1 per worker)
  • Automatic load balancing via Redis queue
  • Improved throughput and high availability
• Comprehensive documentation of dual-worker architecture
  • Multi-worker design explanation in docs/ARCHITECTURE.md
  • Worker scaling guidelines in the Installation section of README.md
  • Performance tuning recommendations
  • Load balancing via Redis queue documentation

• Download failure issues resolved with improved worker architecture
• Enhanced error handling and retry mechanism stability
• Better resource management under high load

• Docker Compose now deploys 2 workers by default (previously 1)

• Chrome extension with automatic M3U8 URL detection
• One-click send to NAS functionality
• Real-time progress monitoring in extension popup
• Settings page with NAS endpoint configuration
• Context menu integration
• Badge notifications for detected URLs

• Phase 2 complete: Worker implementation with playlist parsing (M3U8) and direct downloads (MP4)
• FFmpeg integration for video merging
• Multi-threaded segment downloader
• Retry mechanism with exponential backoff
• Comprehensive error handling

• Enhanced worker architecture for better performance
• Improved logging system
• Updated Docker configurations

• Phase 1 complete: Core infrastructure
• Docker Compose setup for Synology NAS
• PostgreSQL database with schema
• Redis job queue
• FastAPI REST API with basic endpoints
• Worker skeleton with job processing
• Comprehensive documentation
  • Technical specification
  • Architecture documentation
  • Synology setup guides
  • Quick start guide

• Docker multi-service architecture
• Database migrations
• Health check endpoints
• API authentication with API keys

• Initial project specification
• Project structure
• README documentation
• Technical design document