# fairy-root/mac-to-m3u architecture

> Architecture diagram of the GitHub repository fairy-root/mac-to-m3u, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fairy-root/mac-to-m3u
- Repository: https://github.com/fairy-root/mac-to-m3u

## Overview

##### Project type and purpose
- This is a small CLI-based IPTV Mac-to-M3U converter consisting of three standalone Python scripts (`maclist.py`, `macvod.py`, `macshow.py`).
- Each script prompts for an IPTV server URL and a MAC address, invokes HTTP APIs on the IPTV server to retrieve subscription, channel, VOD, or series data, and then outputs an M3U playlist file.

##### File structure
- Top-level files:
- `maclist.py`, `macvod.py`, `macshow.py`: three entry-point scripts.
- `README.md`, `LICENSE`: documentation.
- No subdirectories—each script encapsulates its own workflow.
- Dependencies inferred from README: `requests`, `aiohttp`, `tqdm`.

##### README for additional insights
- Each script follows a similar sequence:
- Prompt → HTTP requests → Data parsing → M3U file generation.
- `macvod.py` and `macshow.py` may use `aiohttp` for concurrent fetching of VOD items or episodes.
- Progress bars (`tqdm`) are used to give feedback on long-running fetch loops.

##### Main components
a. User CLI (invoker)
b. Script module (one of three):
- Input Handler
- HTTP Client Layer (`requests` or `aiohttp`)
- Data Processor / Parser (JSON → internal objects)
- M3U Playlist Generator (writes `.m3u` file to local FS)
c. External IPTV Server (REST-style API endpoints for subscription, channel list, VOD, series)
d. Local File System (output folder for M3U playlists)
e. Third-party libraries (requests, aiohttp, tqdm)

##### Relationships and interactions
- User → (prompts) → Script Input Handler
- Input Handler → (build HTTP request) → HTTP Client
- HTTP Client → (GET/POST) → IPTV Server
- IPTV Server → (JSON/XML payload) → HTTP Client
- HTTP Client → Data Processor → M3U Generator → File System
- `tqdm` wraps loops in Data Processor to show progress

##### Architectural patterns and design principles
- Single-responsibility: each script handles one use case (live channels, VOD, series).
- Layered approach inside each script: Input → Transport → Processing → Output
- Asynchronous I/O used in VOD/series scripts to speed up multiple requests (`aiohttp`).

##### Detail and essential elements
- Break out HTTP Client into sync vs. async paths.
- Concurrency in `macvod.py`/`macshow.py` fetching loops.
- That `tqdm` wraps loop iterations in Data Processor.
- Specify output file naming conventions (e.g., `channels.m3u`).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entities
    User["User CLI"]:::external

    %% CLI Scripts Group
    subgraph "CLI Scripts"
        ML["maclist.py"]:::internal
        MV["macvod.py"]:::internal
        MS["macshow.py"]:::internal
    end

    %% Core Layers
    InputHandler["Input Handler"]:::internal
    HTTPClientSync["HTTP Client (requests)"]:::lib
    HTTPClientAsync["HTTP Client (aiohttp)"]:::lib
    IPTV["IPTV Server API"]:::external
    DataProcessor["Data Processor\n(JSON → objects)\n(tqdm loops)"]:::internal
    M3UGenerator["M3U Playlist Generator"]:::internal
    FileSys[["Local File System\n(cylinder)"]]:::fs

    %% Documentation
    README["README.md"]:::docs
    LICENSE["LICENSE"]:::docs

    %% Connections
    User -->|runs| ML
    User -->|runs| MV
    User -->|runs| MS

    ML -->|invoke| InputHandler
    MV -->|invoke| InputHandler
    MS -->|invoke| InputHandler

    InputHandler -->|build request| HTTPClientSync
    InputHandler -->|build async request| HTTPClientAsync

    HTTPClientSync -->|HTTP GET JSON| IPTV
    HTTPClientAsync -->|HTTP GET JSON| IPTV
    IPTV -->|JSON payload| HTTPClientSync
    IPTV -->|JSON payload| HTTPClientAsync

    HTTPClientSync -->|raw data| DataProcessor
    HTTPClientAsync -->|raw data| DataProcessor

    DataProcessor -->|parsed items| M3UGenerator
    M3UGenerator -->|writes .m3u| FileSys

    %% Documentation links
    README -.-> CLI_Scripts
    LICENSE -.-> CLI_Scripts

    %% Click Events
    click ML "https://github.com/fairy-root/mac-to-m3u/blob/main/maclist.py"
    click MV "https://github.com/fairy-root/mac-to-m3u/blob/main/macvod.py"
    click MS "https://github.com/fairy-root/mac-to-m3u/blob/main/macshow.py"
    click README "https://github.com/fairy-root/mac-to-m3u/blob/main/README.md"
    click LICENSE "https://github.com/fairy-root/mac-to-m3u/tree/main/LICENSE"

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0066CC
    classDef external fill:#DFFFE0,stroke:#00AA00
    classDef lib fill:#FFE8B0,stroke:#CC8400
    classDef fs fill:#E0E0E0,stroke:#888888
    classDef docs fill:#F0F0F0,stroke:#AAAAAA
```
