Coverage for downtify/doctor_audio.py: 75%
63 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""Audio-only fingerprints, so two files can be proven to hold the same
2recording even when their tags and embedded artwork differ.
4Downtify rewrites the tags and the cover of every file it imports from
5slskd, so the library copy and the transfer slskd left behind never have
6the same bytes. Their *audio* is untouched, though: slskd files are not
7transcoded. :func:`audio_md5` asks ``ffmpeg`` to copy the first audio
8stream's packets - no decoding - into its ``md5`` muxer, which hashes
9exactly the encoded audio and nothing else. Two files with the same
10digest carry bit-identical audio, whatever their tags say.
12Hashing reads the whole file, so digests are kept in a small database
13cache keyed by path, size and modification time (:class:`AudioHashCache`).
14"""
16from __future__ import annotations
18import subprocess
19import threading
20from contextlib import AbstractContextManager
21from pathlib import Path
22from typing import Optional
24from loguru import logger
26from downtify.db.config import Dialect
27from downtify.db.core import Connection, Database, as_database
29#: Seconds one file may take; a 200 MB FLAC on a slow disk stays well
30#: inside it.
31HASH_TIMEOUT = 300
33_MD5_PREFIX = 'MD5='
36def audio_md5(path: Path, *, ffmpeg: str = 'ffmpeg') -> Optional[str]:
37 """MD5 of the encoded packets of *path*'s first audio stream.
39 ``None`` when ffmpeg can't read the file (not audio, truncated,
40 missing) - never a guess.
41 """
43 command = [
44 ffmpeg,
45 '-v',
46 'error',
47 '-nostdin',
48 '-i',
49 str(path),
50 '-map',
51 '0:a:0',
52 '-c:a',
53 'copy',
54 '-f',
55 'md5',
56 '-',
57 ]
58 try:
59 done = subprocess.run( # noqa: S603 - fixed argv, no shell
60 command,
61 capture_output=True,
62 text=True,
63 timeout=HASH_TIMEOUT,
64 check=False,
65 )
66 except (OSError, subprocess.TimeoutExpired) as exc:
67 logger.info('doctor: could not hash {}: {}', path, exc)
68 return None
69 if done.returncode != 0:
70 logger.info(
71 'doctor: ffmpeg could not read {}: {}',
72 path,
73 (done.stderr or '').strip()[:200],
74 )
75 return None
76 for raw in (done.stdout or '').splitlines():
77 line = raw.strip()
78 if line.startswith(_MD5_PREFIX):
79 digest = line[len(_MD5_PREFIX) :].strip().lower()
80 if len(digest) == 32:
81 return digest
82 return None
85class AudioHashCache:
86 """``audio_md5`` results, reused while a file's size and mtime hold.
88 *path_or_db* is a SQLite file path or a shared :class:`Database`.
89 """
91 def __init__(self, path_or_db: str | Path | Database) -> None:
92 self.db = as_database(path_or_db, 'doctor_hashes')
93 if isinstance(path_or_db, Database):
94 self.db_path: Path | None = self.db.path
95 else:
96 self.db_path = Path(path_or_db)
97 self._lock = threading.Lock()
98 if self.db.dialect is Dialect.SQLITE:
99 self._init_db()
101 def _init_db(self) -> None:
102 # PostgreSQL gets its table from the migrations.
103 with self._connect() as conn:
104 conn.execute("""
105 CREATE TABLE IF NOT EXISTS audio_hashes (
106 path TEXT PRIMARY KEY,
107 size INTEGER NOT NULL,
108 mtime_ns INTEGER NOT NULL,
109 digest TEXT NOT NULL
110 )
111 """)
113 def _connect(self) -> AbstractContextManager[Connection]:
114 return self.db.connect()
116 def digest(self, path: Path) -> Optional[str]:
117 """The audio digest of *path*, from the cache when still valid."""
119 try:
120 stat = path.stat()
121 except OSError:
122 return None
123 key = str(path)
124 with self._lock, self._connect() as conn:
125 row = conn.execute(
126 'SELECT size, mtime_ns, digest FROM audio_hashes '
127 'WHERE path = ?',
128 (key,),
129 ).fetchone()
130 if row and row[0] == stat.st_size and row[1] == stat.st_mtime_ns:
131 return str(row[2])
132 digest = audio_md5(path)
133 if digest is None:
134 return None
135 with self._lock, self._connect() as conn:
136 conn.execute(
137 'INSERT INTO audio_hashes '
138 '(path, size, mtime_ns, digest) VALUES (?, ?, ?, ?) '
139 'ON CONFLICT (path) DO UPDATE SET '
140 'size = excluded.size, mtime_ns = excluded.mtime_ns, '
141 'digest = excluded.digest',
142 (key, stat.st_size, stat.st_mtime_ns, digest),
143 )
144 return digest
146 def forget(self, paths: list[str]) -> None:
147 if not paths:
148 return
149 with self._lock, self._connect() as conn:
150 conn.executemany(
151 'DELETE FROM audio_hashes WHERE path = ?',
152 [(p,) for p in paths],
153 )