445 lines
9.3 KiB
Markdown
445 lines
9.3 KiB
Markdown
Jag vill implementera en första, skrivskyddad version av funktionaliteten som beskrivs i:
|
|
|
|
```text
|
|
docs/filename-matching-requirements.md
|
|
```
|
|
|
|
Läs hela kravspecifikationen innan du föreslår eller skriver kod.
|
|
|
|
## Projektets nuvarande struktur
|
|
|
|
Projektrot:
|
|
|
|
```text
|
|
/storage/disk1/WCX
|
|
```
|
|
|
|
SQLite-databas:
|
|
|
|
```text
|
|
/storage/disk1/WCX/database/wcx.db
|
|
```
|
|
|
|
Databasschema:
|
|
|
|
```text
|
|
/storage/disk1/WCX/scripts/schema.sql
|
|
```
|
|
|
|
Nya script ska placeras i:
|
|
|
|
```text
|
|
/storage/disk1/WCX/scripts
|
|
```
|
|
|
|
Databasen innehåller tabellen `movie` med bland annat:
|
|
|
|
```text
|
|
id
|
|
name
|
|
duration_seconds
|
|
```
|
|
|
|
Den innehåller även `movie_history` med historiska snapshots och bland annat:
|
|
|
|
```text
|
|
movie_id
|
|
name
|
|
duration_seconds
|
|
archived_at
|
|
change_summary
|
|
```
|
|
|
|
Fältet `movie.name` är filmens kanoniska namn från siten. Det består alltid av ett eller flera personnamn. Flera personer separeras med `+`.
|
|
|
|
Exempel:
|
|
|
|
```text
|
|
Alyn Borav
|
|
Ilona
|
|
Angelique Lapiedra + Scarlett Lapiedra
|
|
```
|
|
|
|
Lokala videofiler kan däremot ha kraftigt nedsmutsade filnamn, exempelvis:
|
|
|
|
```text
|
|
Alyn_Borav_AlynBorav.mp4
|
|
AngeliqueLapiedra_ScarlettLapiedra.mp4
|
|
BrendaBoop_Interwiev_Fisting.mp4
|
|
Busty_Slovakian_Ilona_On_Bed.mp4
|
|
Eden_Ivy_EdenIvy_DP.mp4
|
|
Version_AngelikaFyres_DP.mp4
|
|
```
|
|
|
|
## Uppgift
|
|
|
|
Implementera den första versionen av:
|
|
|
|
```text
|
|
scripts/match_filenames.py
|
|
```
|
|
|
|
Scriptet ska analysera lokala videofiler och försöka matcha dem mot poster i `movie`.
|
|
|
|
Det ska vara konservativt. Korrekthet är viktigare än hur många filer som matchas automatiskt.
|
|
|
|
Resultatet ska klassificeras som:
|
|
|
|
```text
|
|
matched
|
|
ambiguous
|
|
unmatched
|
|
```
|
|
|
|
Osäkra filer ska lämnas för manuell inspektion.
|
|
|
|
## Omfattning för första versionen
|
|
|
|
Första versionen ska:
|
|
|
|
1. Läsa videofiler från en angiven katalog.
|
|
2. Ha stöd för rekursiv sökning.
|
|
3. Läsa `id`, `name` och `duration_seconds` från `movie`.
|
|
4. Läsa historiska längder från `movie_history`.
|
|
5. Normalisera filnamn och databasnamn.
|
|
6. Dela flerpersonsnamn på `+`.
|
|
7. Hitta exakta normaliserade namn i nedsmutsade filnamn.
|
|
8. Hantera namn som skrivits utan separatorer.
|
|
9. Hantera upprepade namn i filnamnet.
|
|
10. Prioritera den mest specifika flerpersonsposten.
|
|
11. Identifiera när filnamnet innehåller flera kända personer.
|
|
12. Läsa videons faktiska längd med `ffprobe`.
|
|
13. Använda längd som en sekundär signal.
|
|
14. Jämföra längden mot både aktuell och historisk sitelängd.
|
|
15. Rangordna kandidater med en förklarbar poängmodell.
|
|
16. Kräva både en tillräckligt hög poäng och en tydlig marginal till kandidat nummer två för `matched`.
|
|
17. Klassificera osäkra resultat som `ambiguous`.
|
|
18. Skriva rapporter för `matched`, `ambiguous` och `unmatched`.
|
|
19. Inte ändra databasen eller några videofiler.
|
|
|
|
## Viktiga säkerhetsregler
|
|
|
|
Scriptet får inte:
|
|
|
|
* ändra databasen
|
|
* flytta filer
|
|
* döpa om filer
|
|
* radera filer
|
|
* registrera alias
|
|
* permanent koppla en fil till en databaspost
|
|
* automatcha en fil enbart på grund av liknande längd
|
|
* automatcha en fil enbart på grund av fuzzy matching
|
|
|
|
Fuzzy matching får gärna förberedas eller användas för kandidatförslag, men ett resultat som är beroende av fuzzy matching ska i första versionen klassificeras som `ambiguous`.
|
|
|
|
En felaktig automatisk match är värre än en omatchad fil.
|
|
|
|
## Namnnormalisering
|
|
|
|
Normaliseringen ska minst:
|
|
|
|
* ta bort filändelsen
|
|
* göra texten gemen
|
|
* normalisera diakritiska tecken
|
|
* ta bort mellanslag
|
|
* ta bort `_`
|
|
* ta bort `-`
|
|
* ta bort `+`
|
|
* ta bort punkter och annan interpunktion
|
|
* behålla bokstäver och siffror
|
|
|
|
Exempel:
|
|
|
|
```text
|
|
Alyn_Borav_AlynBorav.mp4
|
|
→ alynboravalynborav
|
|
|
|
Alyn Borav
|
|
→ alynborav
|
|
```
|
|
|
|
Exakta normaliserade delsträngsträffar ska väga tungt.
|
|
|
|
Extra ord i filnamnet behöver inte tas bort om databasnamnet ändå kan identifieras som en exakt normaliserad delsträng.
|
|
|
|
## Flerpersonsfilmer
|
|
|
|
För:
|
|
|
|
```text
|
|
Angelique Lapiedra + Scarlett Lapiedra
|
|
```
|
|
|
|
ska personerna behandlas separat:
|
|
|
|
```text
|
|
Angelique Lapiedra
|
|
Scarlett Lapiedra
|
|
```
|
|
|
|
Båda dessa filnamn ska kunna matcha posten:
|
|
|
|
```text
|
|
AngeliqueLapiedra_ScarlettLapiedra.mp4
|
|
ScarlettLapiedra_AngeliqueLapiedra.mp4
|
|
```
|
|
|
|
Ordningen ska alltså inte vara avgörande.
|
|
|
|
Om databasen innehåller både:
|
|
|
|
```text
|
|
Scarlett Knight
|
|
Scarlett Knight + Anya Shidlerova
|
|
```
|
|
|
|
och filen heter:
|
|
|
|
```text
|
|
ScarlettKnight_AnyaShidlerova.mp4
|
|
```
|
|
|
|
ska flerpersonsposten rankas högre.
|
|
|
|
## Videolängd
|
|
|
|
Använd `ffprobe` för att läsa faktisk längd utan omkodning.
|
|
|
|
Längd ska endast användas för att stärka eller diskriminera mellan redan rimliga namnkandidater.
|
|
|
|
Beräkna både:
|
|
|
|
```text
|
|
absolut skillnad i sekunder
|
|
procentuell skillnad
|
|
```
|
|
|
|
En första längdmodell kan ungefär vara:
|
|
|
|
```text
|
|
≤ 15 sekunder eller ≤ 1 % mycket stark signal
|
|
≤ 60 sekunder eller ≤ 2 % stark signal
|
|
≤ 3 minuter eller ≤ 5 % rimlig signal
|
|
≤ 10 minuter eller ≤ 10 % svag signal
|
|
> 10 minuter och > 10 % negativ signal
|
|
```
|
|
|
|
Dessa värden ska definieras som tydliga konstanter så att de senare kan justeras.
|
|
|
|
En större längdskillnad ska inte automatiskt ge `unmatched`, eftersom filer kan vara klippta, förlängda eller motsvara en äldre version.
|
|
|
|
Historiska längder från `movie_history` ska kunna ge klassificeringen:
|
|
|
|
```text
|
|
historical_version_match
|
|
```
|
|
|
|
Andra möjliga versionsklassificeringar:
|
|
|
|
```text
|
|
current_version_match
|
|
historical_version_match
|
|
possible_truncated_version
|
|
possible_extended_version
|
|
duration_mismatch
|
|
unknown_version
|
|
```
|
|
|
|
## Automatisk matchning
|
|
|
|
`matched` ska kräva:
|
|
|
|
1. en tillräckligt stark namnmatchning
|
|
2. en totalpoäng över ett tydligt tröskelvärde
|
|
3. en tydlig marginal till kandidat nummer två
|
|
4. inga starka motstridiga namnsignaler
|
|
5. att fuzzy matching inte är den enda avgörande signalen
|
|
|
|
Alla tröskelvärden ska ligga som namngivna konstanter nära början av scriptet.
|
|
|
|
Poängen ska vara förklarbar. Varje kandidat ska innehålla en lista över skäl, exempelvis:
|
|
|
|
```text
|
|
exact normalized full-name match
|
|
all participants matched
|
|
exact participant set
|
|
current duration differs by 5 seconds
|
|
historical duration differs by 8 seconds
|
|
extra known participant found
|
|
fuzzy match required
|
|
```
|
|
|
|
## Kommandoradsgränssnitt
|
|
|
|
Scriptet ska minst stödja:
|
|
|
|
```bash
|
|
scripts/match_filenames.py /path/to/videos
|
|
```
|
|
|
|
Följande argument ska finnas:
|
|
|
|
```text
|
|
--database
|
|
--recursive
|
|
--limit
|
|
--output-directory
|
|
--debug
|
|
--no-ffprobe
|
|
```
|
|
|
|
Standardsökväg för databasen:
|
|
|
|
```text
|
|
/storage/disk1/WCX/database/wcx.db
|
|
```
|
|
|
|
`--no-ffprobe` ska göra det möjligt att testa enbart namnmatchningen.
|
|
|
|
## Rapportering
|
|
|
|
Skapa följande CSV-filer i output-katalogen:
|
|
|
|
```text
|
|
matched.csv
|
|
ambiguous.csv
|
|
unmatched.csv
|
|
```
|
|
|
|
Rapporterna ska vara UTF-8-kodade och ha rubrikrad.
|
|
|
|
`matched.csv` ska minst innehålla:
|
|
|
|
```text
|
|
path
|
|
filename
|
|
file_duration_seconds
|
|
movie_id
|
|
movie_name
|
|
site_duration_seconds
|
|
matched_duration_seconds
|
|
version_classification
|
|
score
|
|
score_margin
|
|
match_reason
|
|
```
|
|
|
|
`ambiguous.csv` ska minst innehålla:
|
|
|
|
```text
|
|
path
|
|
filename
|
|
file_duration_seconds
|
|
candidate_1_id
|
|
candidate_1_name
|
|
candidate_1_score
|
|
candidate_2_id
|
|
candidate_2_name
|
|
candidate_2_score
|
|
reason
|
|
```
|
|
|
|
`unmatched.csv` ska minst innehålla:
|
|
|
|
```text
|
|
path
|
|
filename
|
|
file_duration_seconds
|
|
best_candidate_id
|
|
best_candidate_name
|
|
best_score
|
|
reason
|
|
```
|
|
|
|
Skriv även en sammanfattning till konsolen:
|
|
|
|
```text
|
|
Files analyzed
|
|
Matched
|
|
Ambiguous
|
|
Unmatched
|
|
ffprobe failures
|
|
```
|
|
|
|
I `--debug` ska de bästa kandidaterna och deras poängkomponenter visas per fil.
|
|
|
|
## Tekniska krav
|
|
|
|
Använd Python 3.12 och endast standardbiblioteket i första versionen.
|
|
|
|
`ffprobe` får anropas via `subprocess`.
|
|
|
|
Använd:
|
|
|
|
* `argparse`
|
|
* `csv`
|
|
* `dataclasses`
|
|
* `pathlib`
|
|
* `sqlite3`
|
|
* `subprocess`
|
|
* `unicodedata`
|
|
* tydliga type hints
|
|
|
|
Använd inte externa Python-paket utan att först motivera varför de behövs.
|
|
|
|
Fel i en enskild videofil eller ett `ffprobe`-anrop får inte avbryta hela körningen.
|
|
|
|
Scriptet ska ge tydliga felmeddelanden och avsluta med felkod endast vid övergripande fel, exempelvis:
|
|
|
|
* databasen saknas
|
|
* databasschemat är inkompatibelt
|
|
* inputkatalogen saknas
|
|
* output-katalogen kan inte skapas
|
|
|
|
## Tester
|
|
|
|
Skapa även:
|
|
|
|
```text
|
|
tests/test_match_filenames.py
|
|
```
|
|
|
|
Använd `unittest` från standardbiblioteket.
|
|
|
|
Tester ska minst täcka:
|
|
|
|
1. enkel normalisering
|
|
2. namn med understreck
|
|
3. sammanfogade namn
|
|
4. upprepade namn
|
|
5. extra skräpord
|
|
6. flerpersonsnamn
|
|
7. personer i omvänd ordning
|
|
8. prioritering av flerpersonspost
|
|
9. korta namn
|
|
10. längdpoäng
|
|
11. historisk längdmatchning
|
|
12. otillräcklig marginal mellan kandidater
|
|
13. fuzzy-beroende resultat blir inte `matched`
|
|
14. fil utan kandidat blir `unmatched`
|
|
|
|
Använd temporär SQLite-databas och temporära kataloger i testerna. Testerna får inte använda produktionsdatabasen eller verkliga videofiler.
|
|
|
|
## Arbetssätt
|
|
|
|
Arbeta stegvis.
|
|
|
|
Börja med att:
|
|
|
|
1. läsa den befintliga kravspecifikationen
|
|
2. inspektera relevant databasschema
|
|
3. föreslå en kort implementationstruktur
|
|
4. implementera normalisering och kandidatmodell
|
|
5. implementera namnmatchning
|
|
6. implementera längdmatchning
|
|
7. implementera klassificering
|
|
8. implementera CSV-rapportering
|
|
9. lägga till tester
|
|
10. uppdatera README med användning och begränsningar
|
|
|
|
Gör inga förändringar utanför den här funktionaliteten.
|
|
|
|
När du levererar kod ska du ge hela innehållet för nya eller ändrade filer, inte små kodfragment som kräver besvärlig manuell infogning.
|
|
|
|
När något är osäkert ska du välja den konservativa matchningen och tydligt dokumentera antagandet.
|