StreamStitcher

StreamStitcher is a robust, multi-threaded Python tool designed to download and stitch HLS (HTTP Live Streaming) video segments (.ts files) into a single video file. It is built to handle connection instability with auto-retries, validates segment integrity, and provides real-time progress statistics.

✨ Features

• 🚀 Multi-threaded Downloading: dramatically speeds up downloads by fetching multiple segments concurrently.
• 🛡️ Resilient & Self-Healing: Automatically retries failed chunks and runs a repair phase before merging.
• 🧠 Smart URL Parsing: Auto-detects dataXXX.ts patterns in URLs to generate templates.
• 📊 Real-time Stats: Detailed feedback on download speed, total bytes, and specific segment errors.
• 🔌 Library API: Easily embed the downloader into your own Python scripts.
• ⚙️ Configurable: Customize HTTP headers (User-Agent, Cookies) and thread counts via a setup wizard.

---

📦 Installation

Clone the repository and install the package (and its dependencies) using pip:

git clone https://github.com/yourusername/streamstitcher.git
cd streamstitcher
pip install .

Requirements: Python 3.7+ and requests library.

---

🖥️ CLI Usage

StreamStitcher comes with a built-in interactive command-line interface.

1. Interactive Mode

Simply run the command streamstitcher to start the interactive downloader.

streamstitcher

• URL: Paste the link to any segment of the video (e.g., .../data005.ts). The tool automatically figures out the rest.
• Filename: Enter a name. It supports auto-formatting if you use the delimiter defined in your config (default: " by Teacher On: ").

2. Configuration Wizard

To change default threads, retry counts, or add custom headers (like Cookies or Referers for protected videos):

streamstitcher --setup

---

📚 Python Library API

You can use StreamStitcher as a library to build your own custom video scrapers or automation tools.

Basic Example

from streamstitcher import Stitcher

# 1. Define the URL (can be any segment, e.g., segment 5)
url = "https://example.com/video/stream/data005.ts"

# 2. Initialize the Stitcher
# output_name will be saved in the configured 'output' folder
downloader = Stitcher(url, output_name="my_lesson.ts")

# 3. Start the process (Blocking call)
print("Starting download...")
downloader.start()
print("Done!")

Advanced Example: Custom Progress Bar

You can pass a callback function to on_progress to receive real-time statistics.

import sys
from streamstitcher import Stitcher

def my_progress_hook(stats):
    """
    stats is a dict containing:
    {
        'phase': 'Downloading' | 'Retrying' | 'Merging',
        'index': '005',       # Current segment index
        'ok': 12,             # Successful chunks
        'errors': 0,          # Failed chunks
        'total_size': '5.2 MB',
        'time': '00:00:15'    # Elapsed time
    }
    """
    sys.stdout.write(f"\r[{stats['phase']}] Downloaded: {stats['ok']} chunks ({stats['total_size']})")
    sys.stdout.flush()

# Initialize with the hook
downloader = Stitcher(
    url="https://example.com/video/stream/data001.ts", 
    output_name="lecture_advanced.ts",
    on_progress=my_progress_hook
)

try:
    downloader.start()
except KeyboardInterrupt:
    print("\nDownload canceled.")

---

📂 Configuration

The tool saves a configuration file at ~/.streamstitcher.json. You can edit this manually or use the --setup flag.

Default Configuration:

{
    "filename_delimiter": " by Teacher On: ",
    "default_threads": 10,
    "default_retries": 3,
    "output_folder": "output",
    "temp_folder": "downloaded_segments",
    "custom_headers": {
        "User-Agent": "Mozilla/5.0..."
    }
}

---

🛠️ Development

If you want to modify the code:

1. Core Logic: Located in streamstitcher/core.py.
2. Stats & Utils: Located in streamstitcher/utils.py.
3. CLI Interface: Located in streamstitcher/cli.py.

To run the script directly without installing:

python -m streamstitcher.cli

---

📄 License

MIT License. Free to use and modify.