mediaflow-proxy 2.4.3__tar.gz → 2.4.4__tar.gz

{mediaflow_proxy-2.4.3 → mediaflow_proxy-2.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mediaflow-proxy
-Version: 2.4.3
+Version: 2.4.4
 Summary: A high-performance proxy server for streaming media, supporting HTTP(S), HLS, and MPEG-DASH with real-time DRM decryption.
 Project-URL: Homepage, https://github.com/mhdzumair/mediaflow-proxy
 Project-URL: Repository, https://github.com/mhdzumair/mediaflow-proxy

{mediaflow_proxy-2.4.3 → mediaflow_proxy-2.4.4}/mediaflow_proxy/configs.py

@@ -64,6 +64,12 @@ class Settings(BaseSettings):
     dash_prebuffer_emergency_threshold: int = 90  # Emergency threshold percentage to trigger aggressive cache cleanup.
     dash_prebuffer_inactivity_timeout: int = 60  # Seconds of inactivity before cleaning up stream state.
     dash_segment_cache_ttl: int = 60  # TTL (seconds) for cached media segments; longer = better for slow playback.
+    dash_player_lock_timeout: float = 2.5  # Max wait (seconds) for player requests when a segment lock is busy.
+    dash_prebuffer_lock_timeout: float = 0.25  # Max wait (seconds) for background prebuffer lock acquisition.
+    dash_prefetch_max_concurrent: int = 1  # Max concurrent live DASH prefetch downloads to reduce lock contention.
+    dash_live_initial_media_prebuffer: bool = (
+        False  # Whether manifest-time prebuffer should fetch live media segments (init segments are still prewarmed).
+    )
     mpd_live_init_cache_ttl: int = 60  # TTL (seconds) for live init segment cache; 0 disables caching.
     mpd_live_playlist_depth: int = 8  # Number of recent segments to expose per live playlist variant.
     remux_to_ts: bool = False  # Remux fMP4 segments to MPEG-TS for ExoPlayer/VLC compatibility.

{mediaflow_proxy-2.4.3 → mediaflow_proxy-2.4.4}/mediaflow_proxy/handlers.py

@@ -877,10 +877,12 @@ async def get_segment(
         # - Waiting for existing downloads (via asyncio.Event)
         # - Starting new download if needed
         # - Caching the result
-        # Use a short timeout (1s) for player requests to avoid blocking if prebuffer is busy
-        # This ensures players get fast responses even when background prefetching is active
+        # Player requests should get priority over background prebuffer activity.
+        # Use a configurable lock timeout to balance responsiveness and cache reuse.
         if settings.enable_dash_prebuffer:
-            segment_content = await dash_prebuffer.get_or_download(segment_url, proxy_headers.request, timeout=1.0)
+            segment_content = await dash_prebuffer.get_or_download(
+                segment_url, proxy_headers.request, timeout=settings.dash_player_lock_timeout
+            )
         else:
             # Prebuffer disabled - check cache then download directly
             segment_content = await get_cached_segment(segment_url)

{mediaflow_proxy-2.4.3 → mediaflow_proxy-2.4.4}/mediaflow_proxy/main.py

@@ -12,23 +12,16 @@ from starlette.staticfiles import StaticFiles
 
 from mediaflow_proxy.configs import settings
 from mediaflow_proxy.middleware import UIAccessControlMiddleware
-from mediaflow_proxy.routes import (
-    proxy_router,
-    extractor_router,
-    speedtest_router,
-    playlist_builder_router,
-    xtream_root_router,
-    acestream_router,
-    telegram_router,
-)
+from mediaflow_proxy.routes.proxy import proxy_router
+from mediaflow_proxy.routes.extractor import extractor_router
+from mediaflow_proxy.routes.speedtest import speedtest_router
+from mediaflow_proxy.routes.playlist_builder import playlist_builder_router
+from mediaflow_proxy.routes.xtream import xtream_root_router
 from mediaflow_proxy.schemas import GenerateUrlRequest, GenerateMultiUrlRequest, MultiUrlRequestItem
 from mediaflow_proxy.utils.crypto_utils import EncryptionHandler, EncryptionMiddleware
 from mediaflow_proxy.utils import redis_utils
 from mediaflow_proxy.utils.http_utils import encode_mediaflow_proxy_url
 from mediaflow_proxy.utils.base64_utils import encode_url_to_base64, decode_base64_url, is_base64_url
-from mediaflow_proxy.utils.acestream import acestream_manager
-from mediaflow_proxy.remuxer.video_transcoder import get_hw_capability, HWAccelType
-from mediaflow_proxy.utils.telegram import telegram_manager
 
 logging.basicConfig(level=settings.log_level, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s")
 logger = logging.getLogger(__name__)
@@ -61,30 +54,22 @@ async def lifespan(app: FastAPI):
         # use redis-cli KEYS "mfp:*" | xargs redis-cli DEL
         logger.info("Cache clearing note: Redis entries will expire via TTL")
 
-    # Log transcoding capability
-    hw = get_hw_capability()
-    if hw.accel_type != HWAccelType.NONE and settings.transcode_prefer_gpu:
-        logger.info(
-            "Transcode ready: GPU %s (encoder=%s) | PyAV pipeline",
-            hw.accel_type.value,
-            hw.h264_encoder,
-        )
-    else:
-        logger.info(
-            "Transcode ready: CPU (%s) | PyAV pipeline",
-            hw.h264_encoder,
-        )
-
     yield
 
     # Shutdown
     logger.info("Shutting down...")
     # Close acestream sessions
-    await acestream_manager.close()
-    logger.info("Acestream manager closed")
+    if settings.enable_acestream:
+        from mediaflow_proxy.utils.acestream import acestream_manager
+
+        await acestream_manager.close()
+        logger.info("Acestream manager closed")
     # Close telegram session
-    await telegram_manager.close()
-    logger.info("Telegram manager closed")
+    if settings.enable_telegram:
+        from mediaflow_proxy.utils.telegram import telegram_manager
+
+        await telegram_manager.close()
+        logger.info("Telegram manager closed")
     # Close Redis connections
     await redis_utils.close_redis()
     logger.info("Redis connections closed")
@@ -318,8 +303,14 @@ async def check_base64_url(url: str):
 
 
 app.include_router(proxy_router, prefix="/proxy", tags=["proxy"], dependencies=[Depends(verify_api_key)])
-app.include_router(acestream_router, prefix="/proxy", tags=["acestream"], dependencies=[Depends(verify_api_key)])
-app.include_router(telegram_router, prefix="/proxy", tags=["telegram"], dependencies=[Depends(verify_api_key)])
+if settings.enable_acestream:
+    from mediaflow_proxy.routes.acestream import acestream_router
+
+    app.include_router(acestream_router, prefix="/proxy", tags=["acestream"], dependencies=[Depends(verify_api_key)])
+if settings.enable_telegram:
+    from mediaflow_proxy.routes.telegram import telegram_router
+
+    app.include_router(telegram_router, prefix="/proxy", tags=["telegram"], dependencies=[Depends(verify_api_key)])
 app.include_router(extractor_router, prefix="/extractor", tags=["extractors"], dependencies=[Depends(verify_api_key)])
 app.include_router(speedtest_router, prefix="/speedtest", tags=["speedtest"], dependencies=[Depends(verify_api_key)])
 app.include_router(playlist_builder_router, prefix="/playlist", tags=["playlist"])

{mediaflow_proxy-2.4.3 → mediaflow_proxy-2.4.4}/mediaflow_proxy/mpd_processor.py

@@ -1,6 +1,7 @@
 import asyncio
 import logging
 import math
+import statistics
 import time
 
 from fastapi import Request, Response, HTTPException
@@ -30,6 +31,83 @@ def _resolve_ts_mode(request: Request) -> bool:
     return settings.remux_to_ts
 
 
+def _resolve_nominal_duration_mpd_timescale(profile: dict, segments: list[dict]) -> int | None:
+    """Resolve a stable nominal segment duration (MPD timescale units) for live sequence math."""
+    profile_duration = profile.get("nominal_duration_mpd_timescale")
+    if isinstance(profile_duration, (int, float)) and profile_duration > 0:
+        return int(profile_duration)
+
+    durations = []
+    for seg in segments:
+        seg_duration = seg.get("duration_mpd_timescale")
+        if isinstance(seg_duration, (int, float)) and seg_duration > 0:
+            durations.append(int(seg_duration))
+
+    if durations:
+        # Use median to avoid jumps when first/last live segments are shorter.
+        return int(statistics.median_low(durations))
+    return None
+
+
+def _compute_live_media_sequence(first_segment: dict, profile: dict, segments: list[dict]) -> int:
+    """
+    Compute a stable HLS media sequence for live playlists.
+
+    Strategy:
+    1) If MPD explicitly sets @startNumber, trust segment numbering.
+    2) Otherwise derive sequence from timeline time / nominal duration.
+    3) Fall back to segment number or template start number.
+    """
+    segment_number = first_segment.get("number")
+    if profile.get("segment_template_start_number_explicit") and segment_number is not None:
+        return max(int(segment_number), 1)
+
+    timeline_time = first_segment.get("time")
+    nominal_duration = _resolve_nominal_duration_mpd_timescale(profile, segments)
+    if timeline_time is not None and nominal_duration and nominal_duration > 0:
+        return max(math.floor(int(timeline_time) / nominal_duration), 1)
+
+    if segment_number is not None:
+        return max(int(segment_number), 1)
+
+    template_start = profile.get("segment_template_start_number")
+    if isinstance(template_start, int) and template_start > 0:
+        return template_start
+
+    return 1
+
+
+def _compute_live_playlist_depth(
+    is_ts_mode: bool,
+    effective_start_offset: float | None,
+    extinf_values: list[float],
+) -> int:
+    """
+    Compute a resilient live playlist depth to reduce segment expiry skips.
+
+    We keep a larger floor for fMP4 live (direct mode), and further expand
+    depth based on requested start_offset so players have enough headroom
+    during transient stalls.
+    """
+    configured_depth = max(settings.mpd_live_playlist_depth, 1)
+    depth_floor = 20 if is_ts_mode else 15
+    depth = max(configured_depth, depth_floor)
+
+    if effective_start_offset is not None and effective_start_offset < 0:
+        if extinf_values:
+            segment_duration = statistics.median(extinf_values)
+            if segment_duration <= 0:
+                segment_duration = 4.0
+        else:
+            segment_duration = 4.0
+
+        segments_behind_live_edge = math.ceil(abs(effective_start_offset) / segment_duration)
+        safety_margin = 10 if is_ts_mode else 12
+        depth = max(depth, segments_behind_live_edge + safety_margin)
+
+    return max(depth, 1)
+
+
 async def process_manifest(
     request: Request,
     mpd_dict: dict,
@@ -462,8 +540,8 @@ def build_hls_playlist(
             continue
 
         if is_live:
-            # TS mode uses deeper playlist for ExoPlayer buffering
-            depth = 20 if is_ts_mode else max(settings.mpd_live_playlist_depth, 1)
+            extinf_values_for_depth = [s["extinf"] for s in segments if "extinf" in s]
+            depth = _compute_live_playlist_depth(is_ts_mode, effective_start_offset, extinf_values_for_depth)
             trimmed_segments = segments[-depth:]
         else:
             trimmed_segments = segments
@@ -479,31 +557,13 @@ def build_hls_playlist(
             else:
                 target_duration = math.ceil(max(extinf_values)) if extinf_values else 3
 
-            # Align HLS media sequence with MPD-provided numbering when available
-            if is_ts_mode and is_live:
-                # For live TS, derive sequence from timeline first for stable continuity
-                time_val = first_segment.get("time")
-                duration_val = first_segment.get("duration_mpd_timescale")
-                if time_val is not None and duration_val and duration_val > 0:
-                    sequence = math.floor(time_val / duration_val)
-                else:
-                    sequence = first_segment.get("number") or profile.get("segment_template_start_number") or 1
+            if is_live:
+                sequence = _compute_live_media_sequence(first_segment, profile, trimmed_segments)
             else:
                 mpd_start_number = profile.get("segment_template_start_number")
                 sequence = first_segment.get("number")
-
                 if sequence is None:
-                    # Fallback to MPD template start number
-                    if mpd_start_number is not None:
-                        sequence = mpd_start_number
-                    else:
-                        # As a last resort, derive from timeline information
-                        time_val = first_segment.get("time")
-                        duration_val = first_segment.get("duration_mpd_timescale")
-                        if time_val is not None and duration_val and duration_val > 0:
-                            sequence = math.floor(time_val / duration_val)
-                        else:
-                            sequence = 1
+                    sequence = mpd_start_number if mpd_start_number is not None else 1
 
             hls.extend(
                 [
@@ -543,6 +603,10 @@ def build_hls_playlist(
             if query_params.get("api_password"):
                 init_query_params["api_password"] = query_params["api_password"]
 
+            for k, v in query_params.items():
+                if k.startswith("rp_") or k.startswith("h_"):
+                    init_query_params[k] = v
+
             init_map_url = encode_mediaflow_proxy_url(
                 init_proxy_url,
                 query_params=init_query_params,

{mediaflow_proxy-2.4.3 → mediaflow_proxy-2.4.4}/mediaflow_proxy/remuxer/media_source.py

@@ -13,7 +13,6 @@ from typing import Protocol, runtime_checkable
 from urllib.parse import urlparse, unquote
 
 from mediaflow_proxy.utils.http_client import create_aiohttp_session
-from mediaflow_proxy.utils.telegram import telegram_manager
 
 logger = logging.getLogger(__name__)
 
@@ -142,6 +141,9 @@ class TelegramMediaSource:
         return self._filename_hint
 
     async def stream(self, offset: int = 0, limit: int | None = None) -> AsyncIterator[bytes]:
+        # Lazy import to avoid loading Telegram dependencies for non-Telegram routes.
+        from mediaflow_proxy.utils.telegram import telegram_manager
+
         effective_limit = limit or self._file_size
         if self._use_single_client:
             async for chunk in telegram_manager.stream_media_single(

mediaflow_proxy-2.4.4/mediaflow_proxy/routes/__init__.py

@@ -0,0 +1,43 @@
+__all__ = [
+    "proxy_router",
+    "extractor_router",
+    "speedtest_router",
+    "playlist_builder_router",
+    "xtream_root_router",
+    "acestream_router",
+    "telegram_router",
+]
+
+
+def __getattr__(name: str):
+    # Lazy import routers so importing a single route module does not
+    # pull in optional integrations (telegram/acestream/transcode) at startup.
+    if name == "proxy_router":
+        from .proxy import proxy_router
+
+        return proxy_router
+    if name == "extractor_router":
+        from .extractor import extractor_router
+
+        return extractor_router
+    if name == "speedtest_router":
+        from .speedtest import speedtest_router
+
+        return speedtest_router
+    if name == "playlist_builder_router":
+        from .playlist_builder import playlist_builder_router
+
+        return playlist_builder_router
+    if name == "xtream_root_router":
+        from .xtream import xtream_root_router
+
+        return xtream_root_router
+    if name == "acestream_router":
+        from .acestream import acestream_router
+
+        return acestream_router
+    if name == "telegram_router":
+        from .telegram import telegram_router
+
+        return telegram_router
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{mediaflow_proxy-2.4.3 → mediaflow_proxy-2.4.4}/mediaflow_proxy/routes/acestream.py

@@ -9,7 +9,8 @@ Provides endpoints for proxying acestream content:
 
 import asyncio
 import logging
-from typing import Annotated
+from functools import lru_cache
+from typing import Annotated, TYPE_CHECKING
 from urllib.parse import urlencode, urljoin, urlparse
 
 import aiohttp
@@ -17,8 +18,6 @@ from fastapi import APIRouter, Query, Request, HTTPException, Response, Depends
 from starlette.background import BackgroundTask
 
 from mediaflow_proxy.configs import settings
-from mediaflow_proxy.remuxer.transcode_pipeline import stream_transcode_universal
-from mediaflow_proxy.utils.acestream import acestream_manager, AcestreamSession
 from mediaflow_proxy.utils.http_client import create_aiohttp_session
 from mediaflow_proxy.utils.http_utils import (
     get_original_scheme,
@@ -34,6 +33,22 @@ from mediaflow_proxy.utils.hls_prebuffer import hls_prebuffer
 logger = logging.getLogger(__name__)
 acestream_router = APIRouter()
 
+if TYPE_CHECKING:
+    from mediaflow_proxy.utils.acestream import AcestreamSession
+
+
+def _get_acestream_manager():
+    from mediaflow_proxy.utils.acestream import acestream_manager
+
+    return acestream_manager
+
+
+@lru_cache(maxsize=1)
+def _load_transcode_pipeline():
+    from mediaflow_proxy.remuxer.transcode_pipeline import stream_transcode_universal
+
+    return stream_transcode_universal
+
 
 class AcestreamM3U8Processor(M3U8Processor):
     """
@@ -46,7 +61,7 @@ class AcestreamM3U8Processor(M3U8Processor):
     def __init__(
         self,
         request: Request,
-        session: AcestreamSession,
+        session: "AcestreamSession",
         key_url: str = None,
         force_playlist_proxy: bool = True,
         key_only_proxy: bool = False,
@@ -140,6 +155,7 @@ async def acestream_hls_manifest(
     """
     if not settings.enable_acestream:
         raise HTTPException(status_code=503, detail="Acestream support is disabled")
+    acestream_manager = _get_acestream_manager()
 
     if not infohash and not id:
         raise HTTPException(status_code=400, detail="Either 'infohash' or 'id' parameter is required")
@@ -278,6 +294,7 @@ async def acestream_segment_proxy(
     """
     if not settings.enable_acestream:
         raise HTTPException(status_code=503, detail="Acestream support is disabled")
+    acestream_manager = _get_acestream_manager()
 
     # Use id or infohash for session lookup
     session_key = id or infohash
@@ -368,6 +385,7 @@ async def acestream_ts_stream(
     """
     if not settings.enable_acestream:
         raise HTTPException(status_code=503, detail="Acestream support is disabled")
+    acestream_manager = _get_acestream_manager()
 
     if not infohash and not id:
         raise HTTPException(status_code=400, detail="Either 'infohash' or 'id' parameter is required")
@@ -438,6 +456,7 @@ async def acestream_ts_stream(
             # Use our custom PyAV pipeline with forced video re-encoding
             # (live MPEG-TS sources often have corrupt H.264 bitstreams
             # that browsers reject; re-encoding produces a clean stream).
+            stream_transcode_universal = _load_transcode_pipeline()
             content = stream_transcode_universal(
                 _acestream_ts_source(),
                 force_video_reencode=True,
@@ -509,6 +528,7 @@ async def acestream_status(
     """
     if not settings.enable_acestream:
         raise HTTPException(status_code=503, detail="Acestream support is disabled")
+    acestream_manager = _get_acestream_manager()
 
     if infohash:
         session = acestream_manager.get_session(infohash)

{mediaflow_proxy-2.4.3 → mediaflow_proxy-2.4.4}/mediaflow_proxy/routes/proxy.py

@@ -1,6 +1,7 @@
 import asyncio
 import logging
 import re
+from functools import lru_cache
 from typing import Annotated
 from urllib.parse import quote, unquote
 
@@ -41,19 +42,31 @@ from mediaflow_proxy.utils.http_utils import (
 from mediaflow_proxy.utils.http_client import create_aiohttp_session
 from mediaflow_proxy.utils.m3u8_processor import M3U8Processor
 from mediaflow_proxy.utils.stream_transformers import apply_transformer_to_bytes
-from mediaflow_proxy.remuxer.media_source import HTTPMediaSource
-from mediaflow_proxy.remuxer.transcode_handler import (
-    handle_transcode,
-    handle_transcode_hls_init,
-    handle_transcode_hls_playlist,
-    handle_transcode_hls_segment,
-)
 
 
 logger = logging.getLogger(__name__)
 proxy_router = APIRouter()
 
 
+@lru_cache(maxsize=1)
+def _load_transcode_components():
+    from mediaflow_proxy.remuxer.media_source import HTTPMediaSource
+    from mediaflow_proxy.remuxer.transcode_handler import (
+        handle_transcode,
+        handle_transcode_hls_init,
+        handle_transcode_hls_playlist,
+        handle_transcode_hls_segment,
+    )
+
+    return (
+        HTTPMediaSource,
+        handle_transcode,
+        handle_transcode_hls_init,
+        handle_transcode_hls_playlist,
+        handle_transcode_hls_segment,
+    )
+
+
 def sanitize_url(url: str) -> str:
     """
     Sanitize URL to fix common encoding issues and handle base64 encoded URLs.
@@ -499,6 +512,7 @@ async def transcode_hls_playlist(
     """
     if not settings.enable_transcode:
         raise HTTPException(status_code=503, detail="Transcoding support is disabled")
+    HTTPMediaSource, _, _, handle_transcode_hls_playlist, _ = _load_transcode_components()
     destination = sanitize_url(destination)
     source = HTTPMediaSource(url=destination, headers=dict(proxy_headers.request))
     await source.resolve_file_size()
@@ -540,6 +554,7 @@ async def transcode_hls_init(
     """
     if not settings.enable_transcode:
         raise HTTPException(status_code=503, detail="Transcoding support is disabled")
+    HTTPMediaSource, _, handle_transcode_hls_init, _, _ = _load_transcode_components()
     destination = sanitize_url(destination)
     source = HTTPMediaSource(url=destination, headers=dict(proxy_headers.request))
     await source.resolve_file_size()
@@ -572,6 +587,7 @@ async def transcode_hls_segment(
     """
     if not settings.enable_transcode:
         raise HTTPException(status_code=503, detail="Transcoding support is disabled")
+    HTTPMediaSource, _, _, _, handle_transcode_hls_segment = _load_transcode_components()
     destination = sanitize_url(destination)
     source = HTTPMediaSource(url=destination, headers=dict(proxy_headers.request))
     await source.resolve_file_size()
@@ -693,6 +709,7 @@ async def proxy_stream_endpoint(
     if transcode:
         if not settings.enable_transcode:
             raise HTTPException(status_code=503, detail="Transcoding support is disabled")
+        HTTPMediaSource, handle_transcode, _, _, _ = _load_transcode_components()
         transcode_headers = dict(proxy_headers.request)
         transcode_headers.pop("range", None)
         transcode_headers.pop("if-range", None)

{mediaflow_proxy-2.4.3 → mediaflow_proxy-2.4.4}/mediaflow_proxy/routes/telegram.py

@@ -12,37 +12,50 @@ import asyncio
 import logging
 import re
 import secrets
-from typing import Annotated, Optional
+from functools import lru_cache
+from typing import Annotated, Optional, TYPE_CHECKING
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request, Response
 from pydantic import BaseModel
 
-from telethon import TelegramClient
-from telethon.sessions import StringSession
-
 from mediaflow_proxy.configs import settings
 from mediaflow_proxy.remuxer.media_source import TelegramMediaSource
-from mediaflow_proxy.remuxer.transcode_handler import (
-    handle_transcode,
-    handle_transcode_hls_init,
-    handle_transcode_hls_playlist,
-    handle_transcode_hls_segment,
-)
 from mediaflow_proxy.utils.http_utils import (
     EnhancedStreamingResponse,
     ProxyRequestHeaders,
     apply_header_manipulation,
     get_proxy_headers,
 )
-from mediaflow_proxy.utils.telegram import (
-    TelegramMediaRef,
-    parse_telegram_url,
-    telegram_manager,
-)
 
 logger = logging.getLogger(__name__)
 telegram_router = APIRouter()
 
+if TYPE_CHECKING:
+    from mediaflow_proxy.utils.telegram import TelegramMediaRef
+
+
+def _telegram_utils():
+    from mediaflow_proxy.utils.telegram import TelegramMediaRef, parse_telegram_url, telegram_manager
+
+    return TelegramMediaRef, parse_telegram_url, telegram_manager
+
+
+@lru_cache(maxsize=1)
+def _load_transcode_handlers():
+    from mediaflow_proxy.remuxer.transcode_handler import (
+        handle_transcode,
+        handle_transcode_hls_init,
+        handle_transcode_hls_playlist,
+        handle_transcode_hls_segment,
+    )
+
+    return (
+        handle_transcode,
+        handle_transcode_hls_init,
+        handle_transcode_hls_playlist,
+        handle_transcode_hls_segment,
+    )
+
 
 def get_content_type(mime_type: str, file_name: Optional[str] = None) -> str:
     """Determine content type from mime type or filename."""
@@ -165,6 +178,7 @@ async def telegram_stream(
     """
     if not settings.enable_telegram:
         raise HTTPException(status_code=503, detail="Telegram proxy support is disabled")
+    TelegramMediaRef, parse_telegram_url, telegram_manager = _telegram_utils()
 
     # Get the URL from either parameter
     telegram_url = d or url
@@ -359,7 +373,7 @@ async def telegram_stream(
 
 async def _handle_transcode(
     request: Request,
-    ref: TelegramMediaRef,
+    ref: "TelegramMediaRef",
     file_size: int,
     start_time: float | None = None,
     file_name: str = "",
@@ -371,6 +385,7 @@ async def _handle_transcode(
     passes it to the source-agnostic transcode handler which handles
     cue probing, seeking, and pipeline selection.
     """
+    handle_transcode, _, _, _ = _load_transcode_handlers()
     source = TelegramMediaSource(ref, file_size, file_name=file_name)
     return await handle_transcode(request, source, start_time=start_time)
 
@@ -406,6 +421,7 @@ async def _resolve_telegram_source(
         from fastapi import HTTPException
 
         raise HTTPException(status_code=503, detail="Telegram proxy support is disabled")
+    TelegramMediaRef, parse_telegram_url, telegram_manager = _telegram_utils()
 
     telegram_url = d or url
 
@@ -462,6 +478,7 @@ async def telegram_transcode_hls_playlist(
     """Generate an HLS VOD M3U8 playlist for a Telegram media file."""
     if not settings.enable_transcode:
         raise HTTPException(status_code=503, detail="Transcoding support is disabled")
+    _, _, handle_transcode_hls_playlist, _ = _load_transcode_handlers()
     source = await _resolve_telegram_source(
         d,
         url,
@@ -504,6 +521,7 @@ async def telegram_transcode_hls_init(
     """Serve the fMP4 init segment for a Telegram media file."""
     if not settings.enable_transcode:
         raise HTTPException(status_code=503, detail="Transcoding support is disabled")
+    _, handle_transcode_hls_init, _, _ = _load_transcode_handlers()
     source = await _resolve_telegram_source(
         d,
         url,
@@ -534,6 +552,7 @@ async def telegram_transcode_hls_segment(
     """Serve a single HLS fMP4 media segment for a Telegram media file."""
     if not settings.enable_transcode:
         raise HTTPException(status_code=503, detail="Transcoding support is disabled")
+    _, _, _, handle_transcode_hls_segment = _load_transcode_handlers()
     source = await _resolve_telegram_source(
         d,
         url,
@@ -628,6 +647,7 @@ async def telegram_info(
     """
     if not settings.enable_telegram:
         raise HTTPException(status_code=503, detail="Telegram proxy support is disabled")
+    TelegramMediaRef, parse_telegram_url, telegram_manager = _telegram_utils()
 
     telegram_url = d or url
 
@@ -718,6 +738,7 @@ async def telegram_status():
         }
 
     # Check if client is connected
+    _, _, telegram_manager = _telegram_utils()
     if telegram_manager.is_initialized:
         return {
             "enabled": True,
@@ -783,6 +804,9 @@ async def session_start(request: SessionStartRequest):
     session_id = secrets.token_urlsafe(16)
 
     try:
+        from telethon import TelegramClient
+        from telethon.sessions import StringSession
+
         client = TelegramClient(StringSession(), request.api_id, request.api_hash)
         await client.connect()