trackhound 1.3.0__py3-none-any.whl

trackhound/__init__.py

@@ -0,0 +1,13 @@
+"""Download albums, singles, playlists and tracks by link, tagged and with cover art.
+
+The engine (trackhound.engine) turns a link into files; the window (gui) and
+the command line (cli) are built on top of it.
+
+Copyright (C) 2026 mojave333. Trackhound is free software under the terms of
+the GNU General Public License, version 2 or (at your option) any later
+version; see the LICENSE file. It comes with no warranty.
+"""
+
+# The single source of truth for the version: the release workflow refuses to
+# build when the pushed tag says something else.
+__version__ = "1.3.0"

trackhound/cli.py

@@ -0,0 +1,133 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from . import __version__, logs
+from .i18n import LANGUAGES, set_language, t
+from .engine import batch
+from .engine.downloader import (DEFAULT_OUTPUT_DIR, FOLDER_NAMES, FORMATS, TRACK_NAMES, Downloader,
+                                Options, use_proxy)
+
+
+def _language(argv: list[str] | None) -> str:
+    """--lang, read before argparse so that even the help speaks it."""
+    words = list(sys.argv[1:] if argv is None else argv)
+    for index, word in enumerate(words):
+        if word == "--lang" and index + 1 < len(words):
+            return words[index + 1]
+        if word.startswith("--lang="):
+            return word.split("=", 1)[1]
+    return "system"
+
+
+def _rate(value: str, parser: argparse.ArgumentParser) -> int:
+    """"500K", "2M", "1.5m" — bytes per second; empty means no limit."""
+    if not value:
+        return 0
+    m = re.fullmatch(r"\s*(\d+(?:[.,]\d+)?)\s*([kmg]?)b?/?s?\s*", value, re.I)
+    if not m:
+        parser.error(t("непонятная скорость: {value}. Примеры: 500K, 2M", value=value))
+    scale = {"": 1, "k": 1024, "m": 1024 ** 2, "g": 1024 ** 3}[m.group(2).lower()]
+    return int(float(m.group(1).replace(",", ".")) * scale)
+
+
+def main(argv: list[str] | None = None) -> int:
+    # Every message here is in Russian, which a console or a redirect on an
+    # English Windows cannot encode; --help must not die over that.
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(errors="replace")
+
+    # The language is settled before argparse builds its help
+    set_language(_language(argv))
+    parser = argparse.ArgumentParser(
+        prog="trackhound",
+        description=t("Скачивание альбомов, синглов и треков по ссылке из Spotify, Apple Music, "
+                      "Deezer, YouTube, SoundCloud, Last.fm и сайтов вроде Bandcamp."),
+    )
+    parser.add_argument("links", nargs="*",
+                        help=t("ссылки на альбомы, плейлисты или треки — либо название: "
+                               "«Исполнитель - Альбом»"))
+    parser.add_argument("-o", "--output", type=Path, default=DEFAULT_OUTPUT_DIR,
+                        help=t("папка для музыки (по умолчанию {path})", path=DEFAULT_OUTPUT_DIR))
+    parser.add_argument("-f", "--format", choices=FORMATS, default="m4a",
+                        help=t("формат файлов (по умолчанию m4a — без перекодирования)"))
+    parser.add_argument("-t", "--threads", type=int, default=3,
+                        help=t("сколько треков качать одновременно (по умолчанию 3)"))
+    parser.add_argument("--dry-run", action="store_true",
+                        help=t("только показать найденные совпадения, ничего не скачивать"))
+    parser.add_argument("--cookies-from-browser", default="", metavar=t("БРАУЗЕР"),
+                        help=t("брать cookies из браузера (chrome, edge, firefox…): нужно для видео "
+                               "с возрастным ограничением"))
+    parser.add_argument("--names", choices=TRACK_NAMES, default="auto",
+                        help=t("имена файлов: auto — исполнитель только у гостей, artist — всегда, "
+                               "title — только номер и название"))
+    parser.add_argument("--folders", choices=FOLDER_NAMES, default="flat",
+                        help=t("папки альбомов: flat — «Исполнитель - Альбом (Год)», "
+                               "nested — «Исполнитель\Альбом (Год)», album — «Альбом (Год)»"))
+    parser.add_argument("--limit-rate", default="", metavar=t("СКОРОСТЬ"),
+                        help=t("ограничить скорость: 500K, 2M (по умолчанию без ограничения)"))
+    parser.add_argument("--proxy", default="", metavar=t("АДРЕС"),
+                        help=t("прокси для метаданных и загрузки: http://127.0.0.1:1080, socks5://…"))
+    parser.add_argument("--lang", choices=LANGUAGES, default="system", metavar=t("ЯЗЫК"),
+                        help=t("язык интерфейса и сообщений"))
+    parser.add_argument("--from-file", action="append", default=[], type=Path, metavar=t("ФАЙЛ"),
+                        help=t("взять ссылки и названия из файла: .txt по одной на строку или CSV-выгрузка плейлиста"))
+    parser.add_argument("--replaygain", action="store_true",
+                        help=t("измерить громкость и записать теги ReplayGain; сам звук не меняется"))
+    parser.add_argument("--check", action="store_true",
+                        help=t("показать версию и какие ffmpeg и Deno нашлись, ничего не скачивая"))
+    args = parser.parse_args(argv)
+    logs.setup(console=False)  # warnings already reach the console as text
+
+    options = Options(args.output.expanduser(), args.format, max(1, args.threads), args.dry_run,
+                      args.cookies_from_browser, args.names, args.folders,
+                      _rate(args.limit_rate, parser), args.proxy, args.replaygain)
+    use_proxy(options.proxy)
+    downloader = Downloader(options, log=lambda message: print(message, flush=True))
+
+    if args.check:
+        print(f"Trackhound {__version__}")
+        print(f"ffmpeg: {downloader.ffmpeg or t('не найден')}")
+        for name in ("deno", "node"):
+            print(f"{name}: {downloader.js_runtimes.get(name, {}).get('path', t('не найден'))}")
+        print(t("папка для музыки: {path}", path=options.output_dir))
+        print(f"yt-dlp: {logs.package_version('yt_dlp')}")
+        print(t("журнал: {path}", path=logs.log_file()))
+        for problem in downloader.environment_problems():
+            print(f"⚠ {problem}")
+        return 0
+    for list_file in args.from_file:
+        try:
+            entries, skipped = batch.read(list_file.read_bytes(), list_file.name)
+        except OSError as e:
+            parser.error(t("не прочитать {file}: {error}", file=list_file, error=e))
+        print(t("{file}: взято {count}, не разобрано строк: {skipped}",
+                file=list_file.name, count=len(entries), skipped=skipped))
+        args.links.extend(entries)
+    if not args.links:
+        parser.error(t("укажите ссылку или название (или --check, чтобы проверить установку)"))
+
+    for problem in downloader.environment_problems():
+        print(f"⚠ {problem}", file=sys.stderr)
+
+    failed = 0
+    try:
+        for link in args.links:
+            try:
+                report = downloader.download_link(link)
+            except Exception as e:
+                print(f"✗ {e}", file=sys.stderr)
+                failed += 1
+                continue
+            print(report.summary(args.dry_run), end="\n\n")
+            failed += len(report.failed)
+    except KeyboardInterrupt:
+        print(t("\nОстановлено."), file=sys.stderr)
+        return 130
+    return 1 if failed else 0

trackhound/engine/__init__.py

@@ -0,0 +1,35 @@
+"""The engine: a link or a name in, tagged music files out.
+
+    from pathlib import Path
+    from trackhound.engine import Downloader, Options, resolve
+
+    release = resolve("https://www.deezer.com/album/302127")
+    print(release.album.name, [track.title for track in release.tracks])
+
+    report = Downloader(Options(output_dir=Path("Music"))).download_link(
+        "https://open.spotify.com/album/2noRn2Aes5aoNVsU6iWThc")
+    print(report.summary())
+
+What is importable from here is the public interface, and it keeps working
+across minor versions. The modules behind it (trackhound.engine.sources,
+.matcher and the rest) may change in any release.
+
+The engine knows nothing about the window or the command line, and sets up no
+logging of its own: it writes to the "trackhound" logger and reports progress
+through the callbacks given to Downloader. Its messages speak Russian or
+English, the system's language unless set_language() says otherwise.
+ffmpeg and a JavaScript runtime (Deno, or Node.js 22+) are looked for on PATH.
+"""
+
+from . import batch
+from .downloader import (DEFAULT_OUTPUT_DIR, FOLDER_NAMES, FORMATS, TRACK_NAMES, Downloader,
+                         DownloaderError, Options, Report, find_tool, use_proxy)
+from .i18n import set_language
+from .models import Album, Release, SourceError, Track
+from .sources import resolve, search, search_track
+
+__all__ = [
+    "DEFAULT_OUTPUT_DIR", "FOLDER_NAMES", "FORMATS", "TRACK_NAMES",
+    "Album", "Downloader", "DownloaderError", "Options", "Release", "Report", "SourceError", "Track",
+    "batch", "find_tool", "resolve", "search", "search_track", "set_language", "use_proxy",
+]

trackhound/engine/batch.py

@@ -0,0 +1,123 @@
+"""Reading a list of things to download out of a file.
+
+Two shapes are understood. A plain text file holds one entry per line: a link,
+or a name the way it would be typed into the window, with blank lines and lines
+starting with # ignored. A CSV file is what the playlist exporters write —
+Exportify, TuneMyMusic, Soundiiz — and is read by its column names: a link or
+URI column when there is one, otherwise the track and artist columns.
+
+A row of a CSV export is a single song, so an entry built from its names is
+marked "track:". Searching by name prefers an album over a track, which is
+right for something typed into the window and wrong here: a playlist that has
+the title track of an album would otherwise download the whole album.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import re
+
+LIMIT = 500  # entries taken from one file
+TRACK_PREFIX = "track:"
+_LINK_RE = re.compile(r"https?://\S+|spotify:(?:album|track|playlist):[A-Za-z0-9]{22}", re.I)
+
+# Header names; both sides are reduced by _key() before they are compared
+_LINK_COLUMNS = ("Track URI", "Spotify URI", "URI", "Track URL", "Spotify URL", "URL", "Link",
+                 "Spotify Track URI", "Spotify - id")
+_TRACK_COLUMNS = ("Track Name", "Track", "Title", "Song", "Song Name", "Name")
+_ARTIST_COLUMNS = ("Artist Name(s)", "Artist Name", "Artists", "Artist", "Album Artist")
+
+
+def parse(text: str, name: str = "") -> tuple[list[str], int]:
+    """The entries in a list, in order and without repeats, and how many lines
+    were not understood."""
+    text = text.lstrip("")
+    lower = name.lower()
+    if lower.endswith(".csv") or (not lower.endswith(".txt") and _looks_like_csv(text)):
+        entries, skipped = _from_csv(text)
+    else:
+        entries, skipped = _from_lines(text)
+    seen, unique = set(), []
+    for entry in entries:
+        key = entry.casefold()
+        if key not in seen:
+            seen.add(key)
+            unique.append(entry)
+    return unique[:LIMIT], skipped
+
+
+def read(data: bytes, name: str = "") -> tuple[list[str], int]:
+    """Like parse(), from the bytes of a file in whatever encoding it came in."""
+    for encoding in ("utf-8-sig", "cp1251"):
+        try:
+            return parse(data.decode(encoding), name)
+        except UnicodeDecodeError:
+            continue
+    return parse(data.decode("latin-1"), name)
+
+
+def _key(name: str) -> str:
+    """A header reduced to its letters, so "Artist Name(s)" and "artist names" meet."""
+    return " ".join(re.sub(r"[^\w ]+", "", (name or "").lower()).split())
+
+
+def _from_lines(text: str) -> tuple[list[str], int]:
+    entries, skipped = [], 0
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        links = _LINK_RE.findall(line)
+        if links:
+            entries.extend(link.rstrip(".,;)") for link in links)
+        elif len(line) >= 2:
+            entries.append(" ".join(line.split()))
+        else:
+            skipped += 1
+    return entries, skipped
+
+
+def _looks_like_csv(text: str) -> bool:
+    first = next((line for line in text.splitlines() if line.strip()), "")
+    if not any(mark in first for mark in (",", ";", "\t")):
+        return False
+    cells = {_key(cell) for cell in re.split(r"[,;\t]", first)}
+    known = {_key(name) for name in _TRACK_COLUMNS + _LINK_COLUMNS}
+    return bool(cells & known)
+
+
+def _from_csv(text: str) -> tuple[list[str], int]:
+    try:
+        dialect = csv.Sniffer().sniff(text[:4096], delimiters=",;\t")
+    except csv.Error:
+        dialect = csv.excel
+    reader = csv.DictReader(io.StringIO(text), dialect=dialect)
+    columns = {_key(name): name for name in reader.fieldnames or []}
+
+    def column(candidates):
+        return next((columns[_key(name)] for name in candidates if _key(name) in columns), None)
+
+    link_col, track_col, artist_col = column(_LINK_COLUMNS), column(_TRACK_COLUMNS), column(_ARTIST_COLUMNS)
+
+    entries, skipped = [], 0
+    for row in reader:
+        link = (row.get(link_col) or "").strip() if link_col else ""
+        if _LINK_RE.fullmatch(link):
+            entries.append(link)
+            continue
+        track = " ".join((row.get(track_col) or "").split()) if track_col else ""
+        if track:
+            # Exporters put every artist in one cell; a search for the song goes
+            # by the first of them.
+            artists = (row.get(artist_col) or "").strip() if artist_col else ""
+            artist = re.split(r"\s*[,;]\s*", artists)[0] if artists else ""
+            entries.append(f"{TRACK_PREFIX}{artist} - {track}" if artist else f"{TRACK_PREFIX}{track}")
+            continue
+        found = next((match.group(0) for cell in row.values() if isinstance(cell, str)
+                      for match in [_LINK_RE.search(cell)] if match), None)
+        if found:
+            entries.append(found)
+        elif any(isinstance(cell, str) and cell.strip() for cell in row.values()):
+            skipped += 1
+    return entries, skipped