init

N_m3u8DL_py/README.md

@@ -0,0 +1,90 @@
+# N_m3u8DL-PY
+
+`N_m3u8DL-PY` is a Python reimplementation of the downloader architecture in
+the parent `N_m3u8DL-RE` project. It accepts HLS, DASH and Smooth Streaming
+manifests from HTTP URLs or local files and downloads selected media tracks.
+
+```bash
+python -m n_m3u8dl_py <input> --auto-select
+```
+
+The command line intentionally follows the original project where practical.
+Implemented workflows include:
+
+- HLS master/media playlists, `EXT-X-MAP`, byte ranges, discontinuities and
+  AES-128/AES-128-ECB decryption through the system `openssl` command.
+- DASH `SegmentTemplate`, `SegmentTimeline`, `SegmentList`, `SegmentBase`,
+  BaseURL inheritance and common CENC metadata detection.
+- Smooth Streaming manifest parsing for supported video/audio/text tracks.
+- Parallel segment download, retries, HTTP headers/proxy support, range and
+  ad filtering, binary concat, ffmpeg merge and post-download muxing.
+
+DRM/CENC media cannot be decrypted in Python. The CLI passes supplied keys to
+the configured external decryption tool (`mp4decrypt`, `shaka-packager`, or
+`ffmpeg`) after download where possible.
+
+## Python API
+
+The package exports a stable synchronous API for integration in another Python
+application. It never opens an interactive track picker.
+
+```python
+from pathlib import Path
+
+from n_m3u8dl_py import DownloadRequest, N_m3u8DL, TrackSelection
+
+client = N_m3u8DL()
+media = client.inspect("https://example.com/master.m3u8")
+
+# The default request chooses the best video, the best audio per language,
+# and all subtitle tracks. Track IDs can be selected explicitly when needed.
+result = client.download(
+    media,
+    DownloadRequest(output_dir=Path("downloads"), file_name="episode"),
+)
+
+# Or use the one-call convenience method when track inspection is unnecessary.
+result = client.download_url(
+    "https://example.com/master.m3u8",
+    DownloadRequest(output_dir=Path("downloads")),
+)
+
+video = next(track for track in media.tracks if track.resolution)
+video_only = client.download(
+    media,
+    DownloadRequest(
+        output_dir=Path("downloads"),
+        selection=TrackSelection(track_ids=(video.track_id,)),
+    ),
+)
+```
+
+Pass `on_event` to `inspect()` or `download()` for structured progress. A
+callback may return `False` to cancel the current task; cancellation raises
+`DownloadCancelledError`. Successful calls return `MediaInfo` and
+`DownloadResult`; manifest, selection, and download failures raise the
+corresponding public exception classes.
+
+```python
+from n_m3u8dl_py import DownloadEventKind
+
+def show_progress(event):
+    if event.kind is DownloadEventKind.SEGMENT_COMPLETED:
+        print(event.track_id, event.completed_segments, event.total_segments)
+
+media = client.inspect("playlist.m3u8", on_event=show_progress)
+result = client.download(media, on_event=show_progress)
+```
+
+Create an editable local installation:
+
+```bash
+python -m venv --system-site-packages .venv
+.venv/bin/python -m pip install --no-build-isolation -e .
+```
+
+Run the test suite when `pytest` is available:
+
+```bash
+.venv/bin/python -m pytest tests
+```