feat(plugins): init examples

examples/plugins/player/config.toml

@@ -0,0 +1,15 @@
+[multi-file-provider]
+# Base URL for the anime site
+base_url = "https://multifile.example.site"
+
+# Request timeout in seconds
+timeout = 30
+
+# Preferred video quality
+preferred_quality = "720p"
+
+# Maximum number of search results
+max_results = 25
+
+# Enable debug logging
+debug = false

examples/plugins/player/player.py

@@ -0,0 +1,169 @@
+"""
+VLC player integration for Viu.
+
+This module provides the VlcPlayer class, which implements the BasePlayer interface for the VLC media player.
+"""
+
+import logging
+import shutil
+import subprocess
+
+from viu_media.core.config import VlcConfig
+from viu_media.core.exceptions import ViuError
+from viu_media.core.patterns import TORRENT_REGEX, YOUTUBE_REGEX
+from viu_media.core.utils import detect
+from viu_media.libs.player.base import BasePlayer
+from viu_media.libs.player.params import PlayerParams
+from viu_media.libs.player.types import PlayerResult
+
+logger = logging.getLogger(__name__)
+
+
+class VlcPlayer(BasePlayer):
+    """
+    VLC player implementation for Viu.
+
+    Provides playback functionality using the VLC media player, supporting desktop, mobile, and torrent scenarios.
+    """
+
+    def __init__(self, config: VlcConfig):
+        """
+        Initialize the VlcPlayer with the given VLC configuration.
+
+        Args:
+            config: VlcConfig object containing VLC-specific settings.
+        """
+        self.config = config
+        self.executable = shutil.which("vlc")
+
+    def play(self, params: PlayerParams) -> PlayerResult:
+        """
+        Play the given media using VLC, handling desktop, mobile, and torrent scenarios.
+
+        Args:
+            params: PlayerParams object containing playback parameters.
+
+        Returns:
+            PlayerResult: Information about the playback session.
+        """
+        if not self.executable:
+            raise ViuError("VLC executable not found in PATH.")
+
+        if TORRENT_REGEX.match(params.url) and detect.is_running_in_termux():
+            return self._play_on_mobile(params)
+        else:
+            return self._play_on_desktop(params)
+
+    def play_with_ipc(self, params: PlayerParams, socket_path: str) -> subprocess.Popen:
+        """
+        Not implemented for VLC player.
+        """
+        raise NotImplementedError("play_with_ipc is not implemented for VLC player.")
+
+    def _play_on_mobile(self, params: PlayerParams) -> PlayerResult:
+        """
+        Play media on a mobile device using Android intents.
+
+        Args:
+            params: PlayerParams object containing playback parameters.
+
+        Returns:
+            PlayerResult: Information about the playback session.
+        """
+        if YOUTUBE_REGEX.match(params.url):
+            args = [
+                "nohup",
+                "am",
+                "start",
+                "--user",
+                "0",
+                "-a",
+                "android.intent.action.VIEW",
+                "-d",
+                params.url,
+                "-n",
+                "com.google.android.youtube/.UrlActivity",
+            ]
+        else:
+            args = [
+                "nohup",
+                "am",
+                "start",
+                "--user",
+                "0",
+                "-a",
+                "android.intent.action.VIEW",
+                "-d",
+                params.url,
+                "-n",
+                "org.videolan.vlc/org.videolan.vlc.gui.video.VideoPlayerActivity",
+                "-e",
+                "title",
+                params.title,
+            ]
+
+        subprocess.run(args)
+
+        return PlayerResult(episode=params.episode)
+
+    def _play_on_desktop(self, params: PlayerParams) -> PlayerResult:
+        """
+        Play media on a desktop environment using VLC.
+
+        Args:
+            params: PlayerParams object containing playback parameters.
+
+        Returns:
+            PlayerResult: Information about the playback session.
+        """
+        if TORRENT_REGEX.search(params.url):
+            return self._stream_on_desktop_with_webtorrent_cli(params)
+
+        args = [self.executable, params.url]
+        if params.subtitles:
+            for sub in params.subtitles:
+                args.extend(["--sub-file", sub])
+                break
+        if params.title:
+            args.extend(["--video-title", params.title])
+
+        if self.config.args:
+            args.extend(self.config.args.split(","))
+
+        subprocess.run(args, encoding="utf-8")
+        return PlayerResult(episode=params.episode)
+
+    def _stream_on_desktop_with_webtorrent_cli(
+        self, params: PlayerParams
+    ) -> PlayerResult:
+        """
+        Stream torrent media using the webtorrent CLI and VLC.
+
+        Args:
+            params: PlayerParams object containing playback parameters.
+
+        Returns:
+            PlayerResult: Information about the playback session.
+        """
+        WEBTORRENT_CLI = shutil.which("webtorrent")
+        if not WEBTORRENT_CLI:
+            raise ViuError("Please Install webtorrent cli inorder to stream torrents")
+
+        args = [WEBTORRENT_CLI, params.url, "--vlc"]
+
+        if self.config.args:
+            args.append("--player-args")
+            args.extend(self.config.args.split(","))
+
+        subprocess.run(args)
+        return PlayerResult(episode=params.episode)
+
+
+if __name__ == "__main__":
+    from viu_media.core.constants import APP_ASCII_ART
+
+    print(APP_ASCII_ART)
+    url = input("Enter the url you would like to stream: ")
+    vlc = VlcPlayer(VlcConfig())
+    player_result = vlc.play(PlayerParams(url=url, title="", query="", episode=""))
+    print(player_result)

examples/plugins/player/plugin.info.toml

@@ -0,0 +1,9 @@
+[plugin]
+name = "Multi-File Provider Plugin"
+version = "1.0.0"
+description = "A demo plugin with multiple Python files"
+author = "Viu Developer"
+requires_python = ">=3.11"
+
+[components]
+player = "player:VlcPlayer"

examples/plugins/provider/config.toml

@@ -0,0 +1,18 @@
+# Default configuration for Example Provider Plugin
+# This file is automatically copied to ~/.config/viu/plugins.config.toml during installation
+
+[example-provider]
+# Request timeout in seconds
+timeout = 30
+
+# Preferred video quality
+preferred_quality = "720p"
+
+# Maximum number of search results to return
+max_results = 20
+
+# Custom headers (optional)
+# custom_header = "value"
+
+# Enable debug logging for this plugin
+# debug = false

examples/plugins/provider/constants.py

@@ -0,0 +1,37 @@
+import re
+
+ANIMEPAHE = "animepahe.ru"
+ANIMEPAHE_BASE = f"https://{ANIMEPAHE}"
+ANIMEPAHE_ENDPOINT = f"{ANIMEPAHE_BASE}/api"
+
+SERVERS_AVAILABLE = ["kwik"]
+REQUEST_HEADERS = {
+    "Cookie": "__ddgid_=VvX0ebHrH2DsFZo4; __ddgmark_=3savRpSVFhvZcn5x; __ddg2_=buBJ3c4pNBYKFZNp; __ddg1_=rbVADKr9URtt55zoIGFa; SERVERID=janna; XSRF-TOKEN=eyJpdiI6IjV5bFNtd0phUHgvWGJxc25wL0VJSUE9PSIsInZhbHVlIjoicEJTZktlR2hxR2JZTWhnL0JzazlvZU5TQTR2bjBWZ2dDb0RwUXVUUWNSclhQWUhLRStYSmJmWmUxWkpiYkFRYU12RjFWejlSWHorME1wZG5qQ1U0TnFlNnBFR2laQjN1MjdyNjc5TjVPdXdJb2o5VkU1bEduRW9pRHNDTHh6Sy8iLCJtYWMiOiI0OTc0ZmNjY2UwMGJkOWY2MWNkM2NlMjk2ZGMyZGJmMWE0NTdjZTdkNGI2Y2IwNTIzZmFiZWU5ZTE2OTk0YmU4IiwidGFnIjoiIn0%3D; laravel_session=eyJpdiI6ImxvdlpqREFnTjdaeFJubUlXQWlJVWc9PSIsInZhbHVlIjoiQnE4R3VHdjZ4M1NDdEVWM1ZqMUxtNnVERnJCcmtCUHZKNzRPR2RFbzNFcStTL29xdnVTbWhsNVRBUXEybVZWNU1UYVlTazFqYlN5UjJva1k4czNGaXBTbkJJK01oTUd3VHRYVHBoc3dGUWxHYnFlS2NJVVNFbTFqMVBWdFpuVUgiLCJtYWMiOiI1NDdjZTVkYmNhNjUwZTMxZmRlZmVmMmRlMGNiYjAwYjlmYjFjY2U0MDc1YTQzZThiMTIxMjJlYTg1NTA4YjBmIiwidGFnIjoiIn0%3D; latest=5592",
+    "Host": ANIMEPAHE,
+    "Accept": "application, text/javascript, */*; q=0.01",
+    "Accept-Encoding": "Utf-8",
+    "Referer": ANIMEPAHE_BASE,
+    "DNT": "1",
+    "Connection": "keep-alive",
+    "Sec-Fetch-Dest": "empty",
+    "Sec-Fetch-Site": "same-origin",
+    "Sec-Fetch-Mode": "cors",
+    "TE": "trailers",
+}
+SERVER_HEADERS = {
+    "Host": "kwik.si",
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/png,image/svg+xml,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.5",
+    "Accept-Encoding": "Utf-8",
+    "DNT": "1",
+    "Connection": "keep-alive",
+    "Referer": "https://animepahe.ru/",
+    "Upgrade-Insecure-Requests": "1",
+    "Sec-Fetch-Dest": "iframe",
+    "Sec-Fetch-Mode": "navigate",
+    "Sec-Fetch-Site": "cross-site",
+    "Priority": "u=4",
+    "TE": "trailers",
+}
+JUICY_STREAM_REGEX = re.compile(r"source='(.*)';")
+KWIK_RE = re.compile(r"Player\|(.+?)'")

examples/plugins/provider/extractor.py

@@ -0,0 +1,77 @@
+import re
+
+
+def animepahe_key_creator(c: int, a: int):
+    from ...scraping.utils import encode_base_n
+
+    if c < a:
+        val_a = ""
+    else:
+        val_a = animepahe_key_creator(int(c / a), a)
+    c = c % a
+    if c > 35:
+        val_b = chr(c + 29)
+    else:
+        val_b = encode_base_n(c, 36)
+    return val_a + val_b
+
+
+def animepahe_embed_decoder(
+    encoded_js_p: str,
+    base_a: int,
+    no_of_keys_c: int,
+    values_to_replace_with_k: list,
+):
+    decode_mapper_d: dict = {}
+    for i in range(no_of_keys_c):
+        key = animepahe_key_creator(i, base_a)
+        val = values_to_replace_with_k[i] or key
+        decode_mapper_d[key] = val
+    return re.sub(
+        r"\b\w+\b", lambda match: decode_mapper_d[match.group(0)], encoded_js_p
+    )
+
+
+PARAMETERS_REGEX = re.compile(r"eval\(function\(p,a,c,k,e,d\)\{.*\}\((.*?)\)\)$")
+ENCODE_JS_REGEX = re.compile(r"'(.*?);',(\d+),(\d+),'(.*)'\.split")
+
+
+def process_animepahe_embed_page(embed_page: str):
+    from ...scraping.html_parser import get_element_text_and_html_by_tag
+
+    encoded_js_string = ""
+    embed_page_content = embed_page
+    for _ in range(8):
+        text, html = get_element_text_and_html_by_tag("script", embed_page_content)
+        if not text and html:
+            embed_page_content = re.sub(html, "", embed_page_content)
+            continue
+        if text:
+            encoded_js_string = text.strip()
+            break
+    if not encoded_js_string:
+        return
+    obsfucated_js_parameter_match = PARAMETERS_REGEX.search(encoded_js_string)
+    if not obsfucated_js_parameter_match:
+        return
+    parameter_string = obsfucated_js_parameter_match.group(1)
+    encoded_js_parameter_string = ENCODE_JS_REGEX.search(parameter_string)
+    if not encoded_js_parameter_string:
+        return
+    p: str = encoded_js_parameter_string.group(1)
+    a: int = int(encoded_js_parameter_string.group(2))
+    c: int = int(encoded_js_parameter_string.group(3))
+    k: list = encoded_js_parameter_string.group(4).split("|")
+    return animepahe_embed_decoder(p, a, c, k).replace("\\", "")
+
+
+if __name__ == "__main__":
+    # Testing time
+    filepath = input("Enter file name: ")
+    if filepath:
+        with open(filepath) as file:
+            data = file.read()
+    else:
+        data = """<script>eval(function(p,a,c,k,e,d){e=function(c){return(c<a?'':e(parseInt(c/a)))+((c=c%a)>35?String.fromCharCode(c+29):c.toString(36))};if(!''.replace(/^/,String)){while(c--){d[e(c)]=k[c]||e(c)}k=[function(e){return d[e]}];e=function(){return'\\w+'};c=1};while(c--){if(k[c]){p=p.replace(new RegExp('\\b'+e(c)+'\\b','g'),k[c])}}return p}('f $7={H:a(2){4 B(9.7.h(y z("(?:(?:^|.*;)\\\\s*"+d(2).h(/[\\-\\.\\+\\*]/g,"\\\\$&")+"\\\\s*\\\\=\\\\s*([^;]*).*$)|^.*$"),"$1"))||G},E:a(2,q,3,6,5,t){k(!2||/^(?:8|r\\-v|o|m|p)$/i.D(2)){4 w}f b="";k(3){F(3.J){j K:b=3===P?"; 8=O, I N Q M:u:u A":"; r-v="+3;n;j L:b="; 8="+3;n;j S:b="; 8="+3.Z();n}}9.7=d(2)+"="+d(q)+b+(5?"; m="+5:"")+(6?"; o="+6:"")+(t?"; p":"");4 x},Y:a(2,6,5){k(!2||!11.C(2)){4 w}9.7=d(2)+"=; 8=12, R 10 W l:l:l A"+(5?"; m="+5:"")+(6?"; o="+6:"");4 x},C:a(2){4(y z("(?:^|;\\\\s*)"+d(2).h(/[\\-\\.\\+\\*]/g,"\\\\$&")+"\\\\s*\\\\=")).D(9.7)},X:a(){f c=9.7.h(/((?:^|\\s*;)[^\\=]+)(?=;|$)|^\\s*|\\s*(?:\\=[^;]*)?(?:\\1|$)/g,"").T(/\\s*(?:\\=[^;]*)?;\\s*/);U(f e=0;e<c.V;e++){c[e]=B(c[e])}4 c}};',62,65,'||sKey|vEnd|return|sDomain|sPath|cookie|expires|document|function|sExpires|aKeys|encodeURIComponent|nIdx|var||replace||case|if|00|domain|break|path|secure|sValue|max||bSecure|59|age|false|true|new|RegExp|GMT|decodeURIComponent|hasItem|test|setItem|switch|null|getItem|31|constructor|Number|String|23|Dec|Fri|Infinity|9999|01|Date|split|for|length|1970|keys|removeItem|toUTCString|Jan|this|Thu'.split('|'),0,{}));eval(function(p,a,c,k,e,d){e=function(c){return(c<a?'':e(parseInt(c/a)))+((c=c%a)>35?String.fromCharCode(c+29):c.toString(36))};if(!''.replace(/^/,String)){while(c--){d[e(c)]=k[c]||e(c)}k=[function(e){return d[e]}];e=function(){return'\\w+'};c=1};while(c--){if(k[c]){p=p.replace(new RegExp('\\b'+e(c)+'\\b','g'),k[c])}}return p}('h o=\'1D://1C-E.1B.1A.1z/1y/E/1x/1w/1v.1u\';h d=s.r(\'d\');h 0=B 1t(d,{\'1s\':{\'1r\':i},\'1q\':\'16:9\',\'D\':1,\'1p\':5,\'1o\':{\'1n\':\'1m\'},1l:[\'7-1k\',\'7\',\'1j\',\'1i-1h\',\'1g\',\'1f-1e\',\'1d\',\'D\',\'1c\',\'1b\',\'1a\',\'19\',\'C\',\'18\'],\'C\':{\'17\':i}});8(!A.15()){d.14=o}x{j z={13:12,11:10,Z:Y,X:i,W:i};h c=B A(z);c.V(o);c.U(d);g.c=c}0.3("T",6=>{g.S.R.Q("P")});0.O=1;k v(b,n,m){8(b.y){b.y(n,m,N)}x 8(b.w){b.w(\'3\'+n,m)}}j 4=k(l){g.M.L(l,\'*\')};v(g,\'l\',k(e){j a=e.a;8(a===\'7\')0.7();8(a===\'f\')0.f();8(a===\'u\')0.u()});0.3(\'t\',6=>{4(\'t\')});0.3(\'7\',6=>{4(\'7\')});0.3(\'f\',6=>{4(\'f\')});0.3(\'K\',6=>{4(0.q);s.r(\'.J-I\').H=G(0.q.F(2))});0.3(\'p\',6=>{4(\'p\')});',62,102,'player|||on|sendMessage||event|play|if||data|element|hls|video||pause|window|const|true|var|function|message|eventHandler|eventName|source|ended|currentTime|querySelector|document|ready|stop|bindEvent|attachEvent|else|addEventListener|config|Hls|new|fullscreen|volume|01|toFixed|String|innerHTML|timestamp|ss|timeupdate|postMessage|parent|false|speed|landscape|lock|orientation|screen|enterfullscreen|attachMedia|loadSource|lowLatencyMode|enableWorker|Infinity|backBufferLength|600|maxMaxBufferLength|180|maxBufferLength|src|isSupported||iosNative|capture|airplay|pip|settings|captions|mute|time|current|progress|forward|fast|rewind|large|controls|kwik|key|storage|seekTime|ratio|global|keyboard|Plyr|m3u8|uwu|b92a392054c041a3f9c6eecabeb0e127183f44e547828447b10bca8d77523e6f|03|stream|org|nextcdn|files|eu|https'.split('|'),0,{}))</script>"""
+
+    print(process_animepahe_embed_page(data))

examples/plugins/provider/mappers.py

@@ -0,0 +1,100 @@
+from typing import Any
+
+from viu_media.libs.provider.anime.types import (
+    Anime,
+    AnimeEpisodeInfo,
+    AnimeEpisodes,
+    EpisodeStream,
+    MediaTranslationType,
+    PageInfo,
+    SearchResult,
+    SearchResults,
+    Server,
+)
+
+from .types import (
+    AnimePaheAnimePage,
+    AnimePaheSearchPage,
+)
+
+translation_type_map = {
+    "sub": MediaTranslationType.SUB,
+    "dub": MediaTranslationType.DUB,
+    "raw": MediaTranslationType.RAW,
+}
+
+
+def map_to_search_results(data: AnimePaheSearchPage) -> SearchResults:
+    results = []
+    for result in data["data"]:
+        results.append(
+            SearchResult(
+                id=result["session"],
+                title=result["title"],
+                episodes=AnimeEpisodes(
+                    sub=list(map(str, range(1, result["episodes"] + 1))),
+                    dub=list(map(str, range(1, result["episodes"] + 1))),
+                    raw=list(map(str, range(1, result["episodes"] + 1))),
+                ),
+                media_type=result["type"],
+                score=result["score"],
+                status=result["status"],
+                season=result["season"],
+                poster=result["poster"],
+                year=str(result["year"]),
+            )
+        )
+
+    return SearchResults(
+        page_info=PageInfo(
+            total=data["total"],
+            per_page=data["per_page"],
+            current_page=data["current_page"],
+        ),
+        results=results,
+    )
+
+
+def map_to_anime_result(
+    search_result: SearchResult, anime: AnimePaheAnimePage
+) -> Anime:
+    episodes_info = []
+    episodes = []
+    anime["data"] = sorted(anime["data"], key=lambda k: float(k["episode"]))
+    for ep_info in anime["data"]:
+        episodes.append(str(ep_info["episode"]))
+        episodes_info.append(
+            AnimeEpisodeInfo(
+                id=str(ep_info["id"]),
+                session_id=ep_info["session"],
+                episode=str(ep_info["episode"]),
+                title=ep_info["title"],
+                poster=ep_info["snapshot"],
+                duration=str(ep_info["duration"]),
+            )
+        )
+
+    return Anime(
+        id=search_result.id,
+        title=search_result.title,
+        episodes=AnimeEpisodes(
+            sub=episodes,
+            dub=episodes,
+        ),
+        year=str(search_result.year),
+        poster=search_result.poster,
+        episodes_info=episodes_info,
+    )
+
+
+def map_to_server(
+    episode: AnimeEpisodeInfo, translation_type: Any, quality: Any, stream_link: Any
+) -> Server:
+    links = [
+        EpisodeStream(
+            link=stream_link,
+            quality=quality,
+            translation_type=translation_type_map[translation_type],
+        )
+    ]
+    return Server(name="kwik", links=links, episode_title=episode.title)

examples/plugins/provider/plugin.info.toml

@@ -0,0 +1,10 @@
+[plugin]
+name = "Example Provider Plugin"
+version = "1.0.0"
+description = "A demo provider plugin for testing the viu plugin system"
+author = "Viu Developer"
+homepage = "https://github.com/example/viu-example-plugin"
+requires_python = ">=3.11"
+
+[components]
+provider = "example_provider:ExampleProvider"

examples/plugins/provider/provider.py

@@ -0,0 +1,207 @@
+import logging
+from functools import lru_cache
+from typing import Iterator, Optional
+
+from viu_media.libs.provider.anime.base import BaseAnimeProvider
+from viu_media.libs.provider.anime.params import (
+    AnimeParams,
+    EpisodeStreamsParams,
+    SearchParams,
+)
+from viu_media.libs.provider.anime.types import (
+    Anime,
+    AnimeEpisodeInfo,
+    SearchResult,
+    SearchResults,
+    Server,
+)
+from viu_media.libs.provider.anime.utils.debug import debug_provider
+
+from .constants import (
+    ANIMEPAHE_BASE,
+    ANIMEPAHE_ENDPOINT,
+    JUICY_STREAM_REGEX,
+    REQUEST_HEADERS,
+    SERVER_HEADERS,
+)
+from .extractor import process_animepahe_embed_page
+from .mappers import map_to_anime_result, map_to_search_results, map_to_server
+from .types import AnimePaheAnimePage, AnimePaheSearchPage
+
+logger = logging.getLogger(__name__)
+
+
+class AnimePahe(BaseAnimeProvider):
+    HEADERS = REQUEST_HEADERS
+
+    @debug_provider
+    def search(self, params: SearchParams) -> SearchResults | None:
+        return self._search(params)
+
+    @lru_cache()
+    def _search(self, params: SearchParams) -> SearchResults | None:
+        url_params = {"m": "search", "q": params.query}
+        response = self.client.get(ANIMEPAHE_ENDPOINT, params=url_params)
+        response.raise_for_status()
+        data: AnimePaheSearchPage = response.json()
+        if not data.get("data"):
+            return
+        return map_to_search_results(data)
+
+    @debug_provider
+    def get(self, params: AnimeParams) -> Anime | None:
+        return self._get_anime(params)
+
+    @lru_cache()
+    def _get_anime(self, params: AnimeParams) -> Anime | None:
+        page = 1
+        standardized_episode_number = 0
+
+        search_result = self._get_search_result(params)
+        if not search_result:
+            logger.error(f"No search result found for ID {params.id}")
+            return None
+
+        anime: Optional[AnimePaheAnimePage] = None
+
+        has_next_page = True
+        while has_next_page:
+            logger.debug(f"Loading page: {page}")
+            _anime_page = self._anime_page_loader(
+                m="release",
+                id=params.id,
+                sort="episode_asc",
+                page=page,
+            )
+
+            has_next_page = True if _anime_page["next_page_url"] else False
+            page += 1
+            if not anime:
+                anime = _anime_page
+            else:
+                anime["data"].extend(_anime_page["data"])
+
+        if anime:
+            for episode in anime.get("data", []):
+                if episode["episode"] % 1 == 0:
+                    standardized_episode_number += 1
+                    episode.update({"episode": standardized_episode_number})
+                else:
+                    standardized_episode_number += episode["episode"] % 1
+                    episode.update({"episode": standardized_episode_number})
+                    standardized_episode_number = int(standardized_episode_number)
+
+            return map_to_anime_result(search_result, anime)
+
+    @lru_cache()
+    def _get_search_result(self, params: AnimeParams) -> Optional[SearchResult]:
+        search_results = self._search(SearchParams(query=params.query))
+        if not search_results or not search_results.results:
+            logger.error(f"No search results found for ID {params.id}")
+            return None
+        for search_result in search_results.results:
+            if search_result.id == params.id:
+                return search_result
+
+    @lru_cache()
+    def _anime_page_loader(self, m, id, sort, page) -> AnimePaheAnimePage:
+        url_params = {
+            "m": m,
+            "id": id,
+            "sort": sort,
+            "page": page,
+        }
+        response = self.client.get(ANIMEPAHE_ENDPOINT, params=url_params)
+        response.raise_for_status()
+        return response.json()
+
+    @debug_provider
+    def episode_streams(self, params: EpisodeStreamsParams) -> Iterator[Server] | None:
+        from viu_media.libs.provider.scraping.html_parser import (
+            extract_attributes,
+            get_element_by_id,
+            get_elements_html_by_class,
+        )
+
+        episode = self._get_episode_info(params)
+        if not episode:
+            logger.error(
+                f"Episode {params.episode} doesn't exist for anime {params.anime_id}"
+            )
+            return
+
+        url = f"{ANIMEPAHE_BASE}/play/{params.anime_id}/{episode.session_id}"
+        response = self.client.get(url, follow_redirects=True)
+        response.raise_for_status()
+
+        c = get_element_by_id("resolutionMenu", response.text)
+        if not c:
+            logger.error("Resolution menu not found in the response")
+            return
+        resolutionMenuItems = get_elements_html_by_class("dropdown-item", c)
+        res_dicts = [extract_attributes(item) for item in resolutionMenuItems]
+        quality = None
+        translation_type = None
+        stream_link = None
+
+        # TODO: better document the scraping process
+        for res_dict in res_dicts:
+            # the actual attributes are data attributes in the original html 'prefixed with data-'
+            embed_url = res_dict["src"]
+            data_audio = "dub" if res_dict["audio"] == "eng" else "sub"
+
+            if data_audio != params.translation_type:
+                continue
+
+            if not embed_url:
+                logger.warning("embed url not found please report to the developers")
+                continue
+
+            embed_response = self.client.get(
+                embed_url,
+                headers={
+                    "User-Agent": self.client.headers["User-Agent"],
+                    **SERVER_HEADERS,
+                },
+            )
+            embed_response.raise_for_status()
+            embed_page = embed_response.text
+
+            decoded_js = process_animepahe_embed_page(embed_page)
+            if not decoded_js:
+                logger.error("failed to decode embed page")
+                continue
+            juicy_stream = JUICY_STREAM_REGEX.search(decoded_js)
+            if not juicy_stream:
+                logger.error("failed to find juicy stream")
+                continue
+            juicy_stream = juicy_stream.group(1)
+            quality = res_dict["resolution"]
+            translation_type = data_audio
+            stream_link = juicy_stream
+
+        if translation_type and quality and stream_link:
+            yield map_to_server(episode, translation_type, quality, stream_link)
+
+    @lru_cache()
+    def _get_episode_info(
+        self, params: EpisodeStreamsParams
+    ) -> Optional[AnimeEpisodeInfo]:
+        anime_info = self._get_anime(
+            AnimeParams(id=params.anime_id, query=params.query)
+        )
+        if not anime_info:
+            logger.error(f"No anime info for {params.anime_id}")
+            return
+        if not anime_info.episodes_info:
+            logger.error(f"No episodes info for {params.anime_id}")
+            return
+        for episode in anime_info.episodes_info:
+            if episode.episode == params.episode:
+                return episode
+
+
+if __name__ == "__main__":
+    from viu_media.libs.provider.anime.utils.debug import test_anime_provider
+
+    test_anime_provider(AnimePahe)

examples/plugins/provider/types.py

@@ -0,0 +1,108 @@
+from enum import Enum
+from typing import Literal, TypedDict
+
+
+class Server(Enum):
+    KWIK = "Kwik"
+
+
+class AnimePaheSearchResult(TypedDict):
+    id: str
+    title: str
+    type: str
+    episodes: int
+    status: str
+    season: str
+    year: int
+    score: int
+    poster: str
+    session: str
+
+
+class AnimePaheSearchPage(TypedDict):
+    total: int
+    per_page: int
+    current_page: int
+    last_page: int
+    _from: int
+    to: int
+    data: list[AnimePaheSearchResult]
+
+
+class Episode(TypedDict):
+    id: str
+    anime_id: int
+    episode: float
+    episode2: int
+    edition: str
+    title: str
+    snapshot: str  # episode image
+    disc: str
+    audio: Literal["eng", "jpn"]
+    duration: str  # time 00:00:00
+    session: str
+    filler: int
+    created_at: str
+
+
+class AnimePaheAnimePage(TypedDict):
+    total: int
+    per_page: int
+    current_page: int
+    last_page: int
+    next_page_url: str | None
+    prev_page_url: str | None
+    _from: int
+    to: int
+    data: list[Episode]
+
+
+class AnimePaheEpisodeInfo(TypedDict):
+    title: str
+    episode: float
+    id: str
+    translation_type: Literal["eng", "jpn"]
+    duration: str
+    poster: str
+
+
+class AvailableEpisodesDetail(TypedDict):
+    sub: list[str]
+    dub: list[str]
+    raw: list[str]
+
+
+class AnimePaheAnime(TypedDict):
+    id: str
+    title: str
+    year: int
+    season: str
+    poster: str
+    score: int
+    availableEpisodesDetail: AvailableEpisodesDetail
+    episodesInfo: list[AnimePaheEpisodeInfo]
+
+
+class PageInfo(TypedDict):
+    total: int
+    perPage: int
+    currentPage: int
+
+
+class AnimePaheSearchResults(TypedDict):
+    pageInfo: PageInfo
+    results: list[AnimePaheSearchResult]
+
+
+class AnimePaheStreamLink(TypedDict):
+    quality: str
+    translation_type: Literal["sub", "dub"]
+    link: str
+
+
+class AnimePaheServer(TypedDict):
+    server: Literal["kwik"]
+    links: list[AnimePaheStreamLink]
+    episode_title: str
+    subtitles: list
+    headers: dict

viu_media/core/plugins/manager.py

@@ -15,10 +15,11 @@ from typing import Any, Dict, Literal, Optional, Set, Union
 
 import tomli_w
 from pydantic import ValidationError
+from viu_media.core.exceptions import ViuError
 
 from ..constants import PLUGINS_CONFIG, PLUGINS_DIR, PLUGINS_MANIFEST
 from .model import InstalledPlugin, PluginInfo, PluginManifest
-from viu_media.core.exceptions import ViuError
+
 logger = logging.getLogger(__name__)
 
 ComponentType = Literal["provider", "player", "selector", "command"]
@@ -26,16 +27,19 @@ ComponentType = Literal["provider", "player", "selector", "command"]
 
 class PluginError(ViuError):
     """Base exception for plugin-related errors."""
+
     pass
 
 
 class PluginNotFoundError(ViuError):
     """Raised when a requested plugin is not found."""
+
     pass
 
 
 class PluginLoadError(ViuError):
     """Raised when a plugin fails to load."""
+
     pass
 
 
@@ -101,9 +105,7 @@ class PluginManager:
         plugin_path = plugin_entry.path
 
         if not plugin_path.exists():
-            raise PluginLoadError(
-                f"Plugin path does not exist: {plugin_path}"
-            )
+            raise PluginLoadError(f"Plugin path does not exist: {plugin_path}")
 
         # Load plugin info to get component definition
         try:
@@ -120,9 +122,7 @@ class PluginManager:
 
         # Parse module:class format
         if ":" not in component_def:
-            raise PluginLoadError(
-                f"Invalid component definition: {component_def}"
-            )
+            raise PluginLoadError(f"Invalid component definition: {component_def}")
 
         module_name, class_name = component_def.split(":", 1)
 
@@ -152,9 +152,7 @@ class PluginManager:
 
         # Get the component class/function
         if not hasattr(module, class_name):
-            raise PluginLoadError(
-                f"Module {module_name} does not have {class_name}"
-            )
+            raise PluginLoadError(f"Module {module_name} does not have {class_name}")
 
         component_cls = getattr(module, class_name)
 
@@ -164,13 +162,12 @@ class PluginManager:
 
             # For providers, also inject httpx client like the built-in system
             if component_type == "provider":
-                from ...core.utils.networking import random_user_agent
                 from httpx import Client
 
+                from ...core.utils.networking import random_user_agent
+
                 headers = getattr(component_cls, "HEADERS", {})
-                client = Client(
-                    headers={"User-Agent": random_user_agent(), **headers}
-                )
+                client = Client(headers={"User-Agent": random_user_agent(), **headers})
 
                 try:
                     component = component_cls(client, **plugin_config)
@@ -193,11 +190,7 @@ class PluginManager:
         return component
 
     def add_plugin(
-        self, 
-        component_type: ComponentType, 
-        name: str, 
-        source: str,
-        force: bool = False
+        self, component_type: ComponentType, name: str, source: str, force: bool = False
     ) -> None:
         """Install a plugin from a Git repository.
 
@@ -246,15 +239,11 @@ class PluginManager:
         expected_component = getattr(plugin_info.components, component_type)
         if not expected_component:
             shutil.rmtree(plugin_dir)
-            raise PluginError(
-                f"Plugin does not provide a {component_type} component"
-            )
+            raise PluginError(f"Plugin does not provide a {component_type} component")
 
         # Add to manifest
         plugins_of_type[name] = InstalledPlugin(
-            source=source,
-            path=plugin_dir,
-            version=plugin_info.plugin.version
+            source=source, path=plugin_dir, version=plugin_info.plugin.version
         )
 
         # Save manifest
@@ -336,7 +325,7 @@ class PluginManager:
                 cwd=plugin_path,
                 check=True,
                 capture_output=True,
-                text=True
+                text=True,
             )
             logger.debug(f"Git pull output: {result.stdout}")
         except subprocess.CalledProcessError as e:
@@ -389,12 +378,15 @@ class PluginManager:
         # Add built-in component names
         if component_type == "provider":
             from ...libs.provider.anime.provider import PROVIDERS_AVAILABLE
+
             builtin_names = set(PROVIDERS_AVAILABLE.keys())
         elif component_type == "player":
             from ...libs.player.player import PLAYERS
+
             builtin_names = set(PLAYERS)
         elif component_type == "selector":
             from ...libs.selectors.selector import SELECTORS
+
             builtin_names = set(SELECTORS)
         elif component_type == "command":
             # Commands would need to be handled differently as they're registered in CLI
@@ -428,7 +420,9 @@ class PluginManager:
             with open(PLUGINS_MANIFEST, "rb") as f:
                 data = tomllib.load(f)
             self._manifest = PluginManifest.model_validate(data)
-            logger.debug(f"Loaded plugins manifest with {len(self.list_plugins())} plugins")
+            logger.debug(
+                f"Loaded plugins manifest with {len(self.list_plugins())} plugins"
+            )
         except (OSError, ValidationError, tomllib.TOMLDecodeError) as e:
             logger.error(f"Failed to load plugins manifest: {e}")
             self._manifest = PluginManifest()
@@ -499,7 +493,11 @@ class PluginManager:
         # Handle local file paths
         if source.startswith("file://"):
             return "local", source[7:]  # Remove file:// prefix
-        elif source.startswith("/") or source.startswith("./") or source.startswith("../"):
+        elif (
+            source.startswith("/")
+            or source.startswith("./")
+            or source.startswith("../")
+        ):
             return "local", source
 
         if source.startswith("http"):
@@ -535,26 +533,31 @@ class PluginManager:
         if platform == "local":
             # Handle local repository - just copy the directory
             import shutil
+
             src_path = Path(repo).resolve()
 
             if not src_path.exists():
                 raise PluginError(f"Local repository path does not exist: {src_path}")
 
-            if not (src_path / ".git").exists():
-                raise PluginError(f"Path is not a Git repository: {src_path}")
+            if (src_path / ".git").exists():
+                logger.info(f"Copying local Git repository from {src_path}")
 
-            logger.info(f"Copying local Git repository from {src_path}")
+                try:
+                    # Use git clone to properly copy the repository
+                    subprocess.run(
+                        ["git", "clone", str(src_path), str(dest_path)],
+                        check=True,
+                        capture_output=True,
+                        text=True,
+                    )
+                except subprocess.CalledProcessError as e:
+                    raise PluginError(
+                        f"Failed to clone local repository: {e.stderr}"
+                    ) from e
+            else:
+                logger.warning("Copying non git repo, local plugin")
+                shutil.copytree(src_path, dest_path)
 
-            try:
-                # Use git clone to properly copy the repository
-                subprocess.run(
-                    ["git", "clone", str(src_path), str(dest_path)],
-                    check=True,
-                    capture_output=True,
-                    text=True
-                )
-            except subprocess.CalledProcessError as e:
-                raise PluginError(f"Failed to clone local repository: {e.stderr}") from e
         else:
             # Handle remote repository
             git_url = f"https://{platform}/{repo}.git"
@@ -566,13 +569,15 @@ class PluginManager:
                     ["git", "clone", git_url, str(dest_path)],
                     check=True,
                     capture_output=True,
-                    text=True
+                    text=True,
                 )
             except subprocess.CalledProcessError as e:
                 raise PluginError(f"Failed to clone plugin: {e.stderr}") from e
 
         if not dest_path.exists():
-            raise PluginError("Plugin cloning failed - destination directory was not created")
+            raise PluginError(
+                "Plugin cloning failed - destination directory was not created"
+            )
 
         # Check for git command availability
         try:
@@ -593,7 +598,9 @@ class PluginManager:
             with open(default_config_path, "rb") as f:
                 default_config = tomllib.load(f)
         except (OSError, tomllib.TOMLDecodeError) as e:
-            logger.warning(f"Failed to load default config for plugin '{plugin_name}': {e}")
+            logger.warning(
+                f"Failed to load default config for plugin '{plugin_name}': {e}"
+            )
             return
 
         # Load existing plugins config or create empty dict
@@ -609,7 +616,9 @@ class PluginManager:
 
         # Check if plugin config already exists
         if plugin_name in existing_config:
-            logger.debug(f"Plugin '{plugin_name}' config already exists, skipping default config installation")
+            logger.debug(
+                f"Plugin '{plugin_name}' config already exists, skipping default config installation"
+            )
             return
 
         # Merge the default config
@@ -620,11 +629,17 @@ class PluginManager:
             try:
                 with open(PLUGINS_CONFIG, "wb") as f:
                     tomli_w.dump(existing_config, f)
-                logger.info(f"Installed default configuration for plugin '{plugin_name}'")
+                logger.info(
+                    f"Installed default configuration for plugin '{plugin_name}'"
+                )
             except OSError as e:
-                logger.warning(f"Failed to save default config for plugin '{plugin_name}': {e}")
+                logger.warning(
+                    f"Failed to save default config for plugin '{plugin_name}': {e}"
+                )
         else:
-            logger.debug(f"No config section found for plugin '{plugin_name}' in default config")
+            logger.debug(
+                f"No config section found for plugin '{plugin_name}' in default config"
+            )
 
 
 # Global instance