{"id":48832268,"url":"https://github.com/1999azzar/portable-pms","last_synced_at":"2026-04-14T21:01:49.169Z","repository":{"id":346260928,"uuid":"1189132747","full_name":"1999AZZAR/portable-pms","owner":"1999AZZAR","description":"Portable, zero-dependency media streaming service built in Go.","archived":false,"fork":false,"pushed_at":"2026-03-23T16:45:23.000Z","size":16266,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-23T22:49:59.681Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/1999AZZAR.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2026-03-23T02:23:41.000Z","updated_at":"2026-03-23T16:45:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/1999AZZAR/portable-pms","commit_stats":null,"previous_names":["1999azzar/portable-pms"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/1999AZZAR/portable-pms","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Fportable-pms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Fportable-pms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Fportable-pms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Fportable-pms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/1999AZZAR","download_url":"https://codeload.github.com/1999AZZAR/portable-pms/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/1999AZZAR%2Fportable-pms/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31815080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"ssl_error","status_checked_at":"2026-04-14T18:05:01.765Z","response_time":153,"last_error":"SSL_read: 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":[],"created_at":"2026-04-14T21:01:48.390Z","updated_at":"2026-04-14T21:01:49.147Z","avatar_url":"https://github.com/1999AZZAR.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Portable Media Streamer (PMS)\n\nA zero-dependency media streaming service designed for **true portability**. PMS runs entirely from external storage (USB flash drives, external HDD/SSD) with zero installation or configuration on the host system. All data, metadata, and cache remain on the portable drive.\n\n## Key Features\n\n### True Portability\n*   **Self-Contained**: Binary, UI assets, database, and cache all live on the same drive\n*   **Auto-Detection**: Automatically finds its location and media files\n*   **Cross-Platform**: Single binary works on any Linux/Mac machine\n*   **No Installation**: Plug in, run, unplug - no trace left on host\n*   **Drive-Safe**: Graceful shutdown with WAL-mode SQLite for data integrity\n\n### Mobile-First Design (v1.4.0)\n*   **Professional Streaming UI**: Fullscreen player based on YouTube/Netflix 2026 design\n*   **Auto-Hiding Controls**: Controls fade after 3s, reappear on tap\n*   **Double-Tap to Seek**: Tap left/right to skip ±10 seconds\n*   **Vertical Swipe Navigation**: Swipe up/down between videos (TikTok-style)\n*   **Semi-Transparent Overlays**: Immersive viewing with backdrop blur\n*   **Touch-Optimized**: 48x48px minimum touch targets (Material Design 3)\n*   **Haptic Feedback**: Tactile responses for interactions\n*   **Portrait Mode**: Proper aspect ratio handling for mobile viewing\n\n### Technical Architecture\n\nPMS implements a decentralized media serving model, where the logic and metadata reside on the same drive as the source media.\n\n*   **Core Engine**: Go (Golang) static binary for high concurrency and memory efficiency.\n*   **Media Processor**: FFmpeg static build integration for JIT (Just-In-Time) transcoding.\n*   **Database**: SQLite 3 with WAL mode for persistent metadata storage, residing in the `.metadata/` directory of the mount point.\n*   **Streaming Protocol**: Direct HTTP byte-range streaming by default for minimal CPU/RAM usage, with optional HLS fallback.\n*   **UI System**: Dark watch-style UI with playlist management, recommendations, and recent history.\n\n## Quick Start\n\n### 1. Download/Build\n```bash\ngo build -o bin/pms src/cmd/pms/main.go\n```\n\n### 2. Copy to Portable Drive\n```bash\n# Copy essentials to your USB/external drive\ncp -r bin web start.sh /media/your-drive/\nchmod +x /media/your-drive/start.sh\n```\n\n### 3. Add Media Files\nOrganize your media on the drive:\n```\n/media/your-drive/\n├── Movies/\n├── Series/\n└── JAV/\n```\n\n### 4. Run Anywhere\n```bash\n# Linux/Mac\ncd /media/your-drive\n./start.sh\n\n# Or manually\n./bin/pms --path . --port 8080\n```\n\nAccess at `http://localhost:8080`\n\nAll scanning, metadata, and cache happen on the drive itself. Unplug and move to another computer - everything persists.\n\n## Features\n\n### 1. Media Discovery and Classification\nAutomated indexing logic categorizes media based on directory structure:\n*   **Flat Files**: Single files are indexed as `video`.\n*   **Collections**: Nested series-style folders are indexed as `collection`.\n*   **JAV Pattern**: `\u003croot\u003e/\u003ctop\u003e/JAV/\u003ccode\u003e/\u003cvideo\u003e` is indexed as `jav` (with cover-aware UI support).\n*   **Artist Pattern**: `\u003croot\u003e/\u003ctop\u003e/PORNSTARTS/\u003cartist\u003e/\u003cvideo\u003e` and `\u003croot\u003e/\u003ctop\u003e/UC/\u003cartist\u003e/\u003cvideo\u003e` are indexed as `artist`.\n\n### 2. Playback Compatibility\n*   Direct HTTP range streaming (`/stream`) is the default lightweight path.\n*   Automatic HLS fallback (`/hls`) is used for files that fail browser-native decode support.\n*   HLS segments are generated via FFmpeg and stored in `.metadata/cache/` on the drive.\n\n### 3. Playlist and Queue Management\n*   Root, playlist, type, and search filters.\n*   Episode-aware ordering (with heuristic episode parsing).\n*   Prev/Next/Shuffle/Random controls.\n*   Autoplay next toggle.\n*   Recommendations and recently played rails.\n\n### 4. Path Sanitization\nEnforced directory traversal protection. All media requests are validated against the absolute root of the mount point to prevent unauthorized filesystem access.\n\n### 5. Zero-Footprint Design\n**Nothing is written to the host system.** All application state, including:\n- SQLite database → `.metadata/pms.db`\n- Transcoded segments → `.metadata/cache/`\n- Scan sentinel → `.metadata/scan_done`\n\nEverything stays on the portable drive.\n\n## Stability and Reliability (v1.1.0)\n\n### Production-Ready Features\n*   **Panic Recovery**: Scanner and worker goroutines protected with defer/recover\n*   **Graceful Shutdown**: Handles SIGINT/SIGTERM with coordinated cleanup\n*   **Context Cancellation**: Proper timeout and cancellation for long operations\n*   **Connection Pooling**: Optimized SQLite connection management with WAL mode\n*   **Process Management**: FFmpeg process tracking and cleanup to prevent zombies\n*   **Structured Logging**: JSON logs with configurable levels (debug, info, warn, error)\n*   **Health Checks**: `/health` endpoint for monitoring and orchestration\n*   **Request Timeouts**: 30-second handler timeout with configurable server timeouts\n*   **Enhanced Security**: Improved path validation and access logging\n\n## Usage\n\n### Command Line Flags\n\n```bash\n./bin/pms [flags]\n\nFlags:\n  --path string       Path to media directory (default \".\")\n  --port int          Server port (default 8080)\n  --log-level string  Log level: debug, info, warn, error (default \"info\")\n```\n\n### Launcher Scripts\n\n**Linux/Mac:**\n```bash\n./start.sh\n# Auto-detects drive location, uses sensible defaults\n```\n\n**Windows:**\n```batch\nstart.bat\n```\n\n### Environment Variables\n```bash\nexport PMS_PORT=8080\nexport PMS_LOG_LEVEL=info\n./start.sh\n```\n\n## API Reference\n*   `GET /health`: Health check with database and scanner status\n*   `GET /api/media`: Returns a JSON array of indexed media metadata.\n*   `GET /api/status`: Returns scanner state (`{\"scanning\": true|false}`).\n*   `GET /stream?path=...`: Serves direct file stream with range request support.\n*   `GET /hls/...`: Serves HLS playlists and segments.\n\n## Portable Drive Setup\n\nSee [PORTABLE_SETUP.md](PORTABLE_SETUP.md) for comprehensive guide on:\n- Directory structure\n- Drive safety best practices\n- Performance on different drive types\n- Troubleshooting portable-specific issues\n- Multi-platform setup\n\n## Deployment Options\n\nWhile designed for portable drives, PMS can also be deployed traditionally:\n\n- **Systemd**: `pms.service` included\n- **Docker**: `docker-compose.yml` provided\n- **Kubernetes**: Ready for orchestration\n\nSee [DEPLOYMENT.md](DEPLOYMENT.md) for production deployment guides.\n\n## Monitoring\n\nCheck service health:\n```bash\ncurl http://localhost:8080/health\n```\n\nExample response:\n```json\n{\n  \"status\": \"healthy\",\n  \"version\": \"1.1.0\",\n  \"scanning\": false\n}\n```\n\n## Documentation\n\n- [PORTABLE_SETUP.md](PORTABLE_SETUP.md) - Portable drive configuration and best practices\n- [DEPLOYMENT.md](DEPLOYMENT.md) - Traditional deployment (systemd, Docker, Kubernetes)\n- [CHANGELOG.md](CHANGELOG.md) - Version history and upgrade notes\n- [CONTRIBUTING.md](CONTRIBUTING.md) - Development guidelines\n- [STABILITY_REPORT.md](STABILITY_REPORT.md) - Technical stability improvements\n\n## Performance\n\nTested on various portable drives:\n- **USB 2.0 Flash**: 10-30 files/sec scan, 1-2 concurrent streams\n- **USB 3.0+ Flash**: 50-100 files/sec scan, 3-5 concurrent streams\n- **External SSD**: 100-500 files/sec scan, 10+ concurrent streams\n- **NVMe Enclosure**: 500+ files/sec scan, 20+ concurrent streams\n\n## Security Notes\n\nPMS has no built-in authentication. For public networks:\n- Bind to localhost only\n- Use reverse proxy with authentication\n- Deploy behind VPN (Tailscale, WireGuard)\n- Configure firewall rules\n\nSee [PORTABLE_SETUP.md](PORTABLE_SETUP.md#security-considerations) for details.\n\n## Documentation\n\n- **QUICKSTART.md**: Fast setup guide for portable drives\n- **PORTABLE_SETUP.md**: Comprehensive portability guide\n- **PROFESSIONAL_STREAMING_UI.md**: Research-driven mobile UI design\n- **STABILITY_REPORT.md**: Technical stability improvements\n- **CHANGELOG.md**: Version history\n- **DEPLOYMENT.md**: Production deployment guide\n- **CONTRIBUTING.md**: Contribution guidelines\n\n## License\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1999azzar%2Fportable-pms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F1999azzar%2Fportable-pms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F1999azzar%2Fportable-pms/lists"}