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

1"""Audio-only fingerprints, so two files can be proven to hold the same 

2recording even when their tags and embedded artwork differ. 

3 

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. 

11 

12Hashing reads the whole file, so digests are kept in a small database 

13cache keyed by path, size and modification time (:class:`AudioHashCache`). 

14""" 

15 

16from __future__ import annotations 

17 

18import subprocess 

19import threading 

20from contextlib import AbstractContextManager 

21from pathlib import Path 

22from typing import Optional 

23 

24from loguru import logger 

25 

26from downtify.db.config import Dialect 

27from downtify.db.core import Connection, Database, as_database 

28 

29#: Seconds one file may take; a 200 MB FLAC on a slow disk stays well 

30#: inside it. 

31HASH_TIMEOUT = 300 

32 

33_MD5_PREFIX = 'MD5=' 

34 

35 

36def audio_md5(path: Path, *, ffmpeg: str = 'ffmpeg') -> Optional[str]: 

37 """MD5 of the encoded packets of *path*'s first audio stream. 

38 

39 ``None`` when ffmpeg can't read the file (not audio, truncated, 

40 missing) - never a guess. 

41 """ 

42 

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 

83 

84 

85class AudioHashCache: 

86 """``audio_md5`` results, reused while a file's size and mtime hold. 

87 

88 *path_or_db* is a SQLite file path or a shared :class:`Database`. 

89 """ 

90 

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() 

100 

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 """) 

112 

113 def _connect(self) -> AbstractContextManager[Connection]: 

114 return self.db.connect() 

115 

116 def digest(self, path: Path) -> Optional[str]: 

117 """The audio digest of *path*, from the cache when still valid.""" 

118 

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 

145 

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 )