{"id":23438380,"url":"https://github.com/developerjosh/something","last_synced_at":"2025-09-05T20:41:00.402Z","repository":{"id":268643992,"uuid":"905007447","full_name":"DeveloperJosh/something","owner":"DeveloperJosh","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-20T02:34:19.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-17T08:46:13.667Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/DeveloperJosh.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}},"created_at":"2024-12-18T01:18:23.000Z","updated_at":"2024-12-20T02:34:23.000Z","dependencies_parsed_at":"2024-12-18T03:29:57.845Z","dependency_job_id":"1b5079c6-a12b-4705-b3fb-80b44fdf1ba6","html_url":"https://github.com/DeveloperJosh/something","commit_stats":null,"previous_names":["developerjosh/something"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/DeveloperJosh/something","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeveloperJosh%2Fsomething","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeveloperJosh%2Fsomething/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeveloperJosh%2Fsomething/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeveloperJosh%2Fsomething/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DeveloperJosh","download_url":"https://codeload.github.com/DeveloperJosh/something/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DeveloperJosh%2Fsomething/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273817570,"owners_count":25173634,"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","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":"2024-12-23T14:49:18.433Z","updated_at":"2025-09-05T20:41:00.163Z","avatar_url":"https://github.com/DeveloperJosh.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **HLS Server**\n\nThis project is a secure HTTP Live Streaming (HLS) server built with **Node.js** and **Express**, capable of serving HLS video playlists (`.m3u8`), video segments (`.ts`), and subtitles (`.vtt`). It includes features like **signed URLs**, **rate limiting**, and **secure reverse proxy support**.\n\n---\n\n## **Table of Contents**\n\n1. [Features](#features)  \n2. [Prerequisites](#prerequisites)  \n3. [Installation](#installation)  \n4. [Configuration](#configuration)  \n5. [Running the Server](#running-the-server)  \n6. [Using the Server](#using-the-server)  \n7. [Nginx Reverse Proxy Setup](#nginx-reverse-proxy-setup)  \n8. [Testing with MPV](#testing-with-mpv)  \n9. [Troubleshooting](#troubleshooting)\n\n---\n\n## **Features**\n\n- Serves HLS files (`.m3u8`, `.ts`) and subtitles (`.vtt`) securely.\n- Generates signed URLs to prevent unauthorized access.\n- Includes a rate limiter to prevent abuse.\n- Supports integration with **Nginx** as a reverse proxy.\n- Handles dynamic playlist updates with signed segment URLs.\n\n---\n\n## **Prerequisites**\n\nBefore you begin, ensure you have the following installed:\n\n1. **Node.js** (v18 or higher)  \n2. **NPM** (Node Package Manager)  \n3. **Nginx** (for reverse proxy setup)  \n4. Basic Linux server knowledge  \n\n---\n\n## **Installation**\n\n1. **Clone the Repository**:\n   ```bash\n   git clone https://github.com/yourusername/hls-server.git\n   cd hls-server\n   ```\n\n2. **Install Dependencies**:\n   ```bash\n   npm install\n   ```\n\n3. **Set Up Environment Variables**:\n\n   Create a `.env` file in the root directory with the following content:\n\n   ```env\n   PORT=3000\n   HLS_SECRET=your-very-strong-secret-key\n   ```\n\n   - `PORT`: The port your Express server will run on.\n   - `HLS_SECRET`: A strong key for signing and verifying URLs.\n\n---\n\n## **Running the Server**\n\nStart the server using the following command:\n\n```bash\nnode src/index.js\n```\n\nThe server will start on `http://localhost:3000`.\n\n---\n\n## **Using the Server**\n\n### 1. **Health Check**\n\nTest if the server is running:\n```bash\ncurl http://localhost:3000/health\n```\nResponse:\n```\nServer is running!\n```\n\n### 2. **Generate a Signed URL**\n\nGenerate a signed URL for an HLS file:\n\n```bash\ncurl \"http://localhost:3000/generate-url?file=g/master.m3u8\u0026expiresIn=3600\"\n```\n\n- `file`: The path to the HLS file relative to `/hls/`.\n- `expiresIn`: The validity of the URL in seconds.\n\n**Example Response**:\n```json\n{\n  \"signedUrl\": \"http://localhost:3000/hls/g/master.m3u8?expires=1734496325\u0026signature=...\"\n}\n```\n\n### 3. **Access the HLS Stream**\n\nUse the signed URL to access your HLS stream. Example:\n\n```bash\nhttp://localhost:3000/hls/g/master.m3u8?expires=1734496325\u0026signature=...\n```\n\nYou can also include subtitles (`.vtt`) with players like MPV.\n\n---\n\n## **Nginx Reverse Proxy Setup**\n\nTo allow access to the server without specifying the port, set up an **Nginx reverse proxy**.\n\n### Steps:\n\n1. **Edit the Nginx Configuration**:\n   ```bash\n   sudo nano /etc/nginx/sites-available/hls-server\n   ```\n\n2. **Add the Configuration**:\n   ```nginx\n   server {\n       listen 80;\n       server_name your_server_ip_or_domain;\n\n       location / {\n           proxy_pass http://127.0.0.1:3000;\n           proxy_set_header Host $host;\n           proxy_set_header X-Real-IP $remote_addr;\n           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n           proxy_set_header X-Forwarded-Proto $scheme;\n       }\n\n       access_log /var/log/nginx/access.log;\n       error_log /var/log/nginx/error.log;\n   }\n   ```\n\n3. **Enable and Reload Nginx**:\n   ```bash\n   sudo ln -s /etc/nginx/sites-available/hls-server /etc/nginx/sites-enabled/\n   sudo nginx -t\n   sudo systemctl reload nginx\n   ```\n\nNow you can access the HLS server via:\n```\nhttp://your_server_ip_or_domain/hls/g/master.m3u8\n```\n\n---\n\n## **Testing with MPV**\n\nTo test HLS playback with subtitles using **MPV**:\n\n```bash\nmpv \"http://your_server_ip_or_domain/hls/g/master.m3u8?expires=1734496325\u0026signature=...\"     --sub-file=\"http://your_server_ip_or_domain/hls/g/english.vtt?expires=1734496361\u0026signature=...\"\n```\n\n---\n\n## **Troubleshooting**\n\n1. **Server Not Starting**:\n   - Ensure Node.js and NPM are installed.\n   - Check the `.env` file and verify `HLS_SECRET`.\n\n2. **404 Errors**:\n   - Ensure your HLS files are in the `src/hls` directory.\n   - Verify Nginx reverse proxy is forwarding requests to the correct port.\n\n3. **Invalid or Expired Signature**:\n   - Check the system time on your server.\n   - Ensure the generated `expires` timestamp matches the current time.\n\n4. **Nginx Configuration Issues**:\n   - Test the Nginx configuration:\n     ```bash\n     sudo nginx -t\n     ```\n   - Reload Nginx after changes:\n     ```bash\n     sudo systemctl reload nginx\n     ```\n\n5. **Check Logs**:\n   - Express Server Logs:\n     ```bash\n     node src/index.js\n     ```\n   - Nginx Logs:\n     ```bash\n     sudo tail -f /var/log/nginx/error.log\n     sudo tail -f /var/log/nginx/access.log\n     ```\n\n---\n\n## **Folder Structure**\n\n```\nsomething/\n│\n├── .git/                     # Git folder\n├── node_modules/             # Node.js dependencies\n├── src/                      # Source code\n│   ├── hls/                  # HLS media files (master.m3u8, segments, etc.)\n│   │   └── g/                # Example HLS folder\n│   └── index.js              # Main server file\n├── .env                      # Environment variables\n└── package.json              # NPM package file\n```\n\n---\n\n## **Contributing**\n\nFeel free to contribute by submitting pull requests. For major changes, open an issue first to discuss what you would like to change.\n\n---\n\n## **License**\n\nThis project is licensed under the MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeveloperjosh%2Fsomething","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeveloperjosh%2Fsomething","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeveloperjosh%2Fsomething/lists"}