Merge pull request #587 from BigBrownMF69/feat/replace-audio-from-file

Replace audio from a file; downloads keep hand-replaced files

Author: henriquesebastiao

docs/api-reference.md

@@ -1637,7 +1637,25 @@ Admin. Versions of a library track to [replace its audio](features/replace-audio
 
 Admin. Replace a library track's audio with a YouTube video: `{ "file": "…", "video_id": "7nxWP9BhI7w" }`. `video_id` may also be a SoundCloud track URL (as a SoundCloud candidate carries it). **Response:** `{ "job_id": "replace:<file>", "file": "…" }`.
 
-It runs as a queue job, with the usual [WebSocket](#websocket) progress messages (`song.song_id` is `job_id`, and `song.replace` is `{file, video_id}`), ending in `done` or `error`. The file keeps its path, format, tags and modification date; a failure leaves it untouched. `400` for an invalid video id or file type, `404` for an unknown file, `409` while the same file is already being replaced.
+It runs as a queue job, with the usual [WebSocket](#websocket) progress messages (`song.song_id` is `job_id`, and `song.replace` is `{file, video_id}`), ending in `done` or `error`. The file keeps its path, format, tags and modification date; a failure leaves it untouched. `400` for an invalid video id or file type, `404` for an unknown file, `409` while the same file is already being replaced. Once replaced, the file is [kept from downloads](#get-apilibraryreplaceprotected).
+
+---
+
+### `POST /api/library/replace/upload`
+
+Admin. Replace a library track's audio with an audio file from the admin's device, sent as the raw request body (not multipart). Query: `file` (the track's library path) and `name` (the uploaded file's name, which gives its format: `.mp3`, `.flac`, `.m4a`, `.ogg`, `.opus`, `.wav`, `.aiff`, `.aif`, `.aac` or `.webm`). At most 400 MB.
+
+**Response:** `{ "file", "duration_before", "duration_after", "converted", "hand_replaced": { "file", "source": "file", "replaced_at" } }`.
+
+A file in the track's own format is used as it is; another is converted to it (`converted: true`) at the chosen bitrate. The track keeps its path, tags and modification date, and is then kept from downloads. Works in library-only mode. `400` for a file that isn't readable audio, an empty body or an unsupported type, `404` for an unknown track, `409` while it is already being replaced, `413` above the size limit.
+
+---
+
+### `GET /api/library/replace/protected`
+
+Admin. Whether downloads leave a track alone because its audio was replaced by hand (either way above): `?file=` → `{ "file", "hand_replaced": { "file", "source", "replaced_at" } | null }`. `source` is `youtube`, `soundcloud` or `file`; `replaced_at` is a Unix time.
+
+With **Download again if the file exists** on, a download that would write over such a file counts it as already downloaded instead, and Library upgrade's audio replacement skips it. **`DELETE`** with the same `?file=` lifts that: `{ "file", "forgotten": true | false }`.
 
 ---
 

docs/bg/features/replace-audio.md

@@ -17,6 +17,21 @@ Downtify избира автоматично аудиото за всяка пе
 
 Ако се провали (видеото е недостъпно или YouTube иска вход — вижте [Бисквитки за YouTube](youtube-cookies.md)), файлът ви остава точно както е бил. **Опитай отново** в Опашката пробва същото видео пак, а поставянето на друг линк там замества с него.
 
+## Използване на файл от устройството ви
+
+Когато правилната версия я няма в YouTube (рип от CD, изтегляне от Soulseek, файл, който някой ви е изпратил), използвайте свой файл:
+
+1. В диалога, под **Или използвайте файл от устройството си**, натиснете **Изберете файл…** и изберете аудио файла.
+2. Натиснете **Замяна на аудиото**. Файлът се качва, проверява се, че е четимо аудио, и получава таговете на стария файл.
+
+Файл в собствения формат на песента (`.mp3` за `.mp3`) се използва точно както е. Друг формат (`.mp3`, `.flac`, `.m4a`, `.ogg`, `.opus`, `.wav`, `.aiff`, `.aac` или `.webm`) се преобразува във формата на песента с битрейта, избран в [Настройки за изтегляне](download-settings.md), затова използвайте същия формат, когато го имате. Работи и в режим „само библиотека“, защото нищо не се изтегля от интернет.
+
+## Изтеглянията не пипат заменен файл
+
+Когато **Изтегли отново, ако файлът съществува** е включено, по-късно изтегляне на същата песен (от друг наблюдаван плейлист, следене на изпълнител или изтегляне на плейлист) би записало върху замяната ви каквото намери автоматичното търсене. Затова Downtify помни всеки файл, чието аудио сте заменили, по който и да е начин, и такова изтегляне го брои за вече изтеглен. [Подобри библиотеката](library-upgrade.md) също не сменя аудиото му; обложката, текстовете и таговете му все още могат да се подобряват.
+
+Диалогът показва, когато аудиото на песен е заменено ръчно. **Нека изтеглянията го заменят** премахва това за този файл.
+
 ## Какво остава същото
 
 - **Файлът.** Новото аудио се записва на същия път, в същия формат: `.mp3` остава MP3 (с битрейта, избран в [Настройки за сваляне](download-settings.md)), `.flac` остава FLAC и така нататък. Така всеки плейлист, M3U файл, харесана песен, запис в Navidrome и сдвоено приложение, които сочат към файла, продължават да сочат към него.

docs/de/features/replace-audio.md

@@ -17,6 +17,21 @@ Nur Admins können Audio ersetzen (siehe [Benutzer und Anmeldung](users.md#admin
 
 Schlägt es fehl (das Video ist nicht verfügbar oder YouTube verlangt eine Anmeldung — siehe [YouTube-Cookies](youtube-cookies.md)), bleibt deine Datei genau so, wie sie war. **Erneut versuchen** in der Warteschlange probiert dasselbe Video noch einmal, und das Einfügen eines anderen Links dort ersetzt stattdessen mit diesem.
 
+## Eine Datei von deinem Gerät verwenden
+
+Ist die richtige Version nicht auf YouTube (ein CD-Rip, ein Soulseek-Download, eine Datei, die dir jemand geschickt hat), verwende deine eigene Datei:
+
+1. Drücke im Dialog unter **Oder eine Datei von deinem Gerät verwenden** auf **Datei auswählen…** und wähle die Audiodatei.
+2. Drücke **Audio ersetzen**. Die Datei wird hochgeladen, darauf geprüft, dass sie lesbares Audio ist, und bekommt die Tags der alten Datei.
+
+Eine Datei im eigenen Format des Titels (eine `.mp3` für eine `.mp3`) wird genau so verwendet, wie sie ist. Ein anderes Format (`.mp3`, `.flac`, `.m4a`, `.ogg`, `.opus`, `.wav`, `.aiff`, `.aac` oder `.webm`) wird mit der in den [Download-Einstellungen](download-settings.md) gewählten Bitrate in das Format des Titels umgewandelt; nimm also dasselbe Format, wenn du es hast. Das funktioniert auch im Nur-Bibliothek-Modus, da nichts aus dem Internet geholt wird.
+
+## Downloads lassen eine ersetzte Datei in Ruhe
+
+Ist **Bei vorhandener Datei erneut herunterladen** an, würde ein späterer Download desselben Songs (aus einer anderen überwachten Playlist, einer Künstlerbeobachtung oder einem Playlist-Download) deinen Ersatz mit dem überschreiben, was die automatische Suche findet. Deshalb merkt sich Downtify jede Datei, deren Audio du ersetzt hast, egal auf welchem Weg, und ein solcher Download zählt sie stattdessen als bereits heruntergeladen. Auch [Bibliothek verbessern](library-upgrade.md) tauscht ihr Audio nicht aus; Cover, Songtexte und Tags können weiterhin verbessert werden.
+
+Der Dialog zeigt an, wenn das Audio eines Titels von Hand ersetzt wurde. **Downloads dürfen sie ersetzen** hebt das für diese Datei auf.
+
 ## Was gleich bleibt
 
 - **Die Datei.** Das neue Audio wird im selben Pfad und im selben Format geschrieben: Eine `.mp3` bleibt MP3 (mit der in den [Download-Einstellungen](download-settings.md) gewählten Bitrate), eine `.flac` bleibt FLAC und so weiter. So zeigen alle Playlists, M3U-Dateien, gelikten Songs, Navidrome-Einträge und gekoppelten Apps, die auf die Datei verweisen, weiterhin auf sie.

docs/el/features/replace-audio.md

@@ -17,6 +17,21 @@ icon: lucide/replace
 
 Αν αποτύχει (το βίντεο δεν είναι διαθέσιμο ή το YouTube ζητά σύνδεση — δες [Cookies YouTube](youtube-cookies.md)), το αρχείο σου μένει ακριβώς όπως ήταν. Το **Επανάληψη** στην Ουρά ξαναδοκιμάζει το ίδιο βίντεο, και η επικόλληση άλλου συνδέσμου εκεί αντικαθιστά με εκείνον.
 
+## Χρήση αρχείου από τη συσκευή σας
+
+Όταν η σωστή εκδοχή δεν υπάρχει στο YouTube (rip από CD, λήψη από το Soulseek, αρχείο που σας έστειλε κάποιος), χρησιμοποιήστε δικό σας αρχείο:
+
+1. Στο παράθυρο διαλόγου, στην ενότητα **Ή χρησιμοποιήστε ένα αρχείο από τη συσκευή σας**, πατήστε **Επιλογή αρχείου…** και επιλέξτε το αρχείο ήχου.
+2. Πατήστε **Αντικατάσταση ήχου**. Το αρχείο μεταφορτώνεται, ελέγχεται ότι είναι αναγνώσιμος ήχος και παίρνει τις ετικέτες του παλιού αρχείου.
+
+Ένα αρχείο στη μορφή του κομματιού (ένα `.mp3` για ένα `.mp3`) χρησιμοποιείται ακριβώς όπως είναι. Μια άλλη μορφή (`.mp3`, `.flac`, `.m4a`, `.ogg`, `.opus`, `.wav`, `.aiff`, `.aac` ή `.webm`) μετατρέπεται στη μορφή του κομματιού με τον ρυθμό bit που επιλέξατε στις [Ρυθμίσεις λήψης](download-settings.md), οπότε χρησιμοποιήστε την ίδια μορφή όταν την έχετε. Λειτουργεί και σε λειτουργία μόνο βιβλιοθήκης, αφού τίποτα δεν λαμβάνεται από το διαδίκτυο.
+
+## Οι λήψεις αφήνουν ήσυχο ένα αντικατεστημένο αρχείο
+
+Με ενεργή τη ρύθμιση **Λήψη ξανά αν υπάρχει το αρχείο**, μια μεταγενέστερη λήψη του ίδιου τραγουδιού (από άλλη παρακολουθούμενη playlist, παρακολούθηση καλλιτέχνη ή λήψη playlist) θα έγραφε πάνω στην αντικατάστασή σας ό,τι βρει η αυτόματη αναζήτηση. Γι’ αυτό το Downtify θυμάται κάθε αρχείο του οποίου αντικαταστήσατε τον ήχο, με όποιον τρόπο, και μια τέτοια λήψη το μετρά ως ήδη ληφθέν. Ούτε η [Αναβάθμιση βιβλιοθήκης](library-upgrade.md) αλλάζει τον ήχο του· το εξώφυλλο, οι στίχοι και οι ετικέτες του μπορούν ακόμη να αναβαθμιστούν.
+
+Το παράθυρο διαλόγου δείχνει πότε ο ήχος ενός κομματιού αντικαταστάθηκε χειροκίνητα. Το **Να το αντικαθιστούν οι λήψεις** το καταργεί για αυτό το αρχείο.
+
 ## Τι μένει ίδιο
 
 - **Το αρχείο.** Ο νέος ήχος γράφεται στην ίδια διαδρομή, στην ίδια μορφή: ένα `.mp3` μένει MP3 (με το bitrate που επιλέχθηκε στις [Ρυθμίσεις λήψης](download-settings.md)), ένα `.flac` μένει FLAC κ.ο.κ. Έτσι κάθε λίστα, αρχείο M3U, αγαπημένο τραγούδι, καταχώριση Navidrome και συνδεδεμένη εφαρμογή που δείχνει στο αρχείο συνεχίζει να δείχνει σε αυτό.

docs/es/features/replace-audio.md

@@ -17,6 +17,21 @@ Solo los administradores pueden reemplazar audio (consulta [Usuarios e inicio de
 
 Si falla (el vídeo no está disponible, o YouTube pide iniciar sesión — consulta [Cookies de YouTube](youtube-cookies.md)), tu archivo queda exactamente como estaba. **Reintentar** en la Cola prueba el mismo vídeo otra vez, y pegar otro enlace allí reemplaza con ese.
 
+## Usar un archivo de tu dispositivo
+
+Si la versión correcta no está en YouTube (un rip de CD, una descarga de Soulseek, un archivo que alguien te envió), usa tu propio archivo:
+
+1. En el diálogo, en **O usa un archivo de tu dispositivo**, pulsa **Elegir un archivo…** y elige el archivo de audio.
+2. Pulsa **Reemplazar audio**. El archivo se sube, se comprueba que sea audio legible y recibe las etiquetas del archivo anterior.
+
+Un archivo en el formato propio de la pista (un `.mp3` para un `.mp3`) se usa exactamente como está. Otro formato (`.mp3`, `.flac`, `.m4a`, `.ogg`, `.opus`, `.wav`, `.aiff`, `.aac` o `.webm`) se convierte al formato de la pista con la tasa de bits elegida en [Ajustes de descarga](download-settings.md), así que usa el mismo formato cuando lo tengas. También funciona en el modo solo biblioteca, porque no se descarga nada de internet.
+
+## Las descargas no tocan un archivo reemplazado
+
+Con **Descargar de nuevo si el archivo existe** activado, una descarga posterior de la misma canción (de otra playlist monitorizada, del seguimiento de un artista o de la descarga de una playlist) sobrescribiría tu reemplazo con lo que encuentre la búsqueda automática. Por eso Downtify recuerda cada archivo cuyo audio reemplazaste, de cualquiera de las dos formas, y esa descarga lo cuenta como ya descargado. [Mejorar biblioteca](library-upgrade.md) tampoco cambia su audio; su portada, letras y etiquetas se pueden seguir mejorando.
+
+El diálogo indica cuándo el audio de una pista se reemplazó a mano. **Dejar que las descargas lo reemplacen** lo quita para ese archivo.
+
 ## Qué permanece igual
 
 - **El archivo.** El audio nuevo se escribe en la misma ruta, en el mismo formato: un `.mp3` sigue siendo MP3 (con la tasa de bits elegida en [Ajustes de descarga](download-settings.md)), un `.flac` sigue siendo FLAC, y así sucesivamente. Así, toda playlist, archivo M3U, canción favorita, entrada de Navidrome y app vinculada que apunta al archivo sigue apuntando a él.

docs/features/replace-audio.md

@@ -17,6 +17,21 @@ Only admins can replace audio (see [Users & Sign-in](users.md#admins-and-users))
 
 If it fails (the video is unavailable, or YouTube asks to sign in — see [YouTube cookies](youtube-cookies.md)), your file is left exactly as it was. **Retry** in the Queue tries the same video again, and pasting another link there replaces with that one instead.
 
+## Using a file from your device
+
+When the right version isn't on YouTube (a CD rip, a Soulseek download, a file someone sent you), use your own file:
+
+1. In the dialog, under **Or use a file from your device**, press **Choose a file…** and pick the audio file.
+2. Press **Replace audio**. The file is uploaded, checked to be readable audio, and given the old file's tags.
+
+A file in the track's own format (an `.mp3` for an `.mp3`) is used exactly as it is. Another format (`.mp3`, `.flac`, `.m4a`, `.ogg`, `.opus`, `.wav`, `.aiff`, `.aac` or `.webm`) is converted to the track's format at the bitrate chosen in [Download settings](download-settings.md), so use the same format when you have it. This works in library-only mode too, since nothing is fetched from the internet.
+
+## Downloads leave a replaced file alone
+
+With **Download again if the file exists** on, a later download of the same song (from another monitored playlist, an artist watch or a playlist download) would write over your replacement with whatever the automatic match finds. So Downtify remembers every file whose audio you replaced, either way, and such a download counts it as already downloaded instead. [Library upgrade](library-upgrade.md) doesn't swap its audio either; its cover, lyrics and tags can still be upgraded.
+
+The dialog says when a track's audio was replaced by hand. **Let downloads replace it** lifts this for that file.
+
 ## What stays the same
 
 - **The file.** The new audio is written to the same path, in the same format: an `.mp3` stays MP3 (at the bitrate chosen in [Download settings](download-settings.md)), a `.flac` stays FLAC, and so on. So every playlist, M3U file, liked song, Navidrome entry and paired app that points at the file keeps pointing at it.

docs/fr/features/replace-audio.md

@@ -17,6 +17,21 @@ Seuls les administrateurs peuvent remplacer l’audio (voir [Utilisateurs et con
 
 En cas d’échec (la vidéo est indisponible, ou YouTube demande de se connecter — voir [Cookies YouTube](youtube-cookies.md)), votre fichier reste exactement tel qu’il était. **Réessayer** dans la File retente la même vidéo, et coller un autre lien à cet endroit remplace avec celui-là.
 
+## Utiliser un fichier de votre appareil
+
+Si la bonne version n’est pas sur YouTube (un rip de CD, un téléchargement Soulseek, un fichier qu’on vous a envoyé), utilisez votre propre fichier :
+
+1. Dans la boîte de dialogue, sous **Ou utilisez un fichier de votre appareil**, appuyez sur **Choisir un fichier…** et choisissez le fichier audio.
+2. Appuyez sur **Remplacer l’audio**. Le fichier est envoyé, vérifié comme audio lisible, et reçoit les tags de l’ancien fichier.
+
+Un fichier dans le format du morceau (un `.mp3` pour un `.mp3`) est utilisé exactement tel quel. Un autre format (`.mp3`, `.flac`, `.m4a`, `.ogg`, `.opus`, `.wav`, `.aiff`, `.aac` ou `.webm`) est converti dans le format du morceau, au débit choisi dans les [Paramètres de téléchargement](download-settings.md) : utilisez donc le même format quand vous l’avez. Cela fonctionne aussi en mode bibliothèque seule, puisque rien n’est récupéré sur Internet.
+
+## Les téléchargements laissent un fichier remplacé tranquille
+
+Avec **Retélécharger si le fichier existe** activé, un téléchargement ultérieur de la même chanson (depuis une autre playlist surveillée, le suivi d’un artiste ou le téléchargement d’une playlist) écraserait votre remplacement par ce que trouve la recherche automatique. Downtify retient donc chaque fichier dont vous avez remplacé l’audio, d’une façon ou de l’autre, et un tel téléchargement le compte comme déjà téléchargé. [Améliorer la bibliothèque](library-upgrade.md) ne remplace pas non plus son audio ; sa pochette, ses paroles et ses tags peuvent toujours être améliorés.
+
+La boîte de dialogue indique quand l’audio d’un morceau a été remplacé à la main. **Laisser les téléchargements le remplacer** lève cette protection pour ce fichier.
+
 ## Ce qui reste identique
 
 - **Le fichier.** Le nouvel audio est écrit au même chemin, dans le même format : un `.mp3` reste du MP3 (au débit choisi dans les [Réglages de téléchargement](download-settings.md)), un `.flac` reste du FLAC, et ainsi de suite. Ainsi, chaque playlist, fichier M3U, titre liké, entrée Navidrome et application associée qui pointe vers le fichier continue d’y pointer.