PerfectSentenceShadowing

EN

An mpv script for perfect sentence shadowing (Refold Stage 3 → B: Pronunciation Training), and/or chorusing : loop a sentence in content you are watching, record your pronunciation via microphone, and compare your take against the original — including a "flow-verlapping" overlay where pronunciation mismatches produce audible dissonance. The goal is to try to get as close to original pronunciation as currently possible. Everything happens inside mpv with single keypresses.

Requirements

mpv and ffmpeg (on PATH; the macOS version also finds Homebrew packages). On macOS, sox is also required (brew install sox) — it performs the recording.

Install

Copy the file for your platform into the mpv scripts directory (~/.config/mpv/scripts/ on Linux and macOS, %APPDATA%\mpv\scripts\ on Windows) — install exactly one:

• perfect-sentence-shadowing.lua — GNU/Linux (PulseAudio/PipeWire)
• perfect-sentence-shadowing-macos.lua — macOS (records via sox from the default input device)
• perfect-sentence-shadowing-windows.lua — Windows (records from the first DirectShow capture device, detected automatically)

macOS setup

Allow mpv to register as an application needing microphone access (adjust the path to where your mpv.app is located):

plutil -insert NSMicrophoneUsageDescription \
-string "Records your voice for pronunciation practice" \
/Applications/mpv.app/Contents/Info.plist
codesign --force --deep --sign - /Applications/mpv.app

The OS asks for the microphone permission once, on the first recording.

Windows microphone

To use a specific microphone instead of the auto-detected one, list your devices:

ffmpeg -list_devices true -f dshow -i dummy

and set the local mic line in the script:

local mic = {"-f", "dshow", "-audio_buffer_size", "50", "-i", "audio=YOUR DEVICE NAME"}

For the most problem-free experience it's recommended to use GNU/Linux. macOS and Windows variations have been tested less thorougly.

Usage

1. Press l at the start of a sentence and l again at its end — mpv loops it and the audio clip is extracted automatically. Listen as many times as you like.
2. Press Alt+r, imitate the sentence, press Alt+r again. Playback pauses while you record; after saving, your take and the original play back to back.
3. Re-record with Alt+r until satisfied, then press Alt+n to move on.

Key	Action
l l (loop)	Set A-B loop and extract the sentence (mpv built-in loop)
Alt+r (record)	Start/stop recording your imitation
Alt+o (original)	Play the original sentence
Alt+m (mine)	Play your recording
Alt+c (compare)	Play your recording, then the original
Alt+b (both)	Play both overlaid — mistakes create dissonance
Alt+n (next)	Done with this sentence: clear loop, delete created files, resume

Clearing the loop with a third l press also deletes the working files, so keep the loop set until you are finished with the sentence.

Notes

• Working files live in the system temporary directory and are deleted when the loop is cleared.
• If the relative volume of your voice in an overlay/mix sounds too silent or too loud against the original, it's possible to adjust it by changing 3dB from [1:a]volume=3dB[r]; in the overlay() function to a different value. Increasing the value will raise the volume, decreasing will lower it.
• Changes to script will take effect for new mpv instances, i.e. application restart might be needed.

UK

mpv скрипт для ідеального наслідування речень (Refold, Стадія 3 → Б: Тренування вимови) і/або хорового повторення: створіть цикл з реченням у контенті, який дивитесь, запишіть власну вимову на мікрофон і порівнюйте її з оригіналом — включно з накладанням у стилі «flow-verlapping», де розбіжності у вимові створюють відчутний дисонанс. Мета — спробувати максимально наблизитися до оригінальної вимови. Усе відбувається всередині mpv одиничними натисканнями клавіш.

Вимоги

mpv та ffmpeg (доступні через PATH; версія для macOS також знаходить пакети з Homebrew). На macOS додатково потрібен sox (brew install sox) — саме він виконує запис.

Встановлення

Скопіюйте файл для вашої платформи до каталогу скриптів mpv (~/.config/mpv/scripts/ на Linux і macOS, %APPDATA%\mpv\scripts\ на Windows) — встановіть рівно один:

• perfect-sentence-shadowing.lua — GNU/Linux (PulseAudio/PipeWire)
• perfect-sentence-shadowing-macos.lua — macOS (запис виконується через sox з пристрою введення за замовчуванням)
• perfect-sentence-shadowing-windows.lua — Windows (запис з першого пристрою захоплення DirectShow, який визначається автоматично)

Налаштування macOS

Дозвольте mpv зареєструватись як програма, якій необхідний доступ до мікрофона (замініть шлях на розташування вашого mpv.app):

plutil -insert NSMicrophoneUsageDescription \
-string "Records your voice for pronunciation practice" \
/Applications/mpv.app/Contents/Info.plist
codesign --force --deep --sign - /Applications/mpv.app

ОС одноразово запитає дозвіл на використання мікрофона під час першого запису.

Мікрофон на Windows

Щоб використовувати конкретний мікрофон замість автоматично визначеного, перегляньте список пристроїв:

ffmpeg -list_devices true -f dshow -i dummy

і змініть рядок local mic у скрипті на:

local mic = {"-f", "dshow", "-audio_buffer_size", "50", "-i", "audio=НАЗВА ВАШОГО ПРИСТРОЮ"}

Для найбільш безпроблемного досвіду рекомендовано використовувати GNU/Linux. Варіації для macOS та Windows пройшли менш ретельне тестування.

Використання

1. Натисніть l на початку речення і ще раз l у його кінці — mpv замкне його у повторюваний цикл, а аудіо-кліп буде витягнуто автоматично. Слухайте скільки завгодно разів.
2. Натисніть Alt+r, повторіть речення, натисніть Alt+r ще раз. Під час запису відтворення ставиться на паузу; після збереження ваш запис і оригінал відтворюються один за одним.
3. Перезаписуйте через Alt+r, доки не будете задоволені, потім натисніть Alt+n, щоб рухатися далі.

Клавіша	Дія
l l (loop/цикл)	Встановити цикл A-B і витягнути речення (вбудований цикл mpv)
Alt+r (record/запис)	Почати/зупинити запис вашої імітації
Alt+o (original/оригінал)	Відтворити оригінальне речення
Alt+m (mine/мій)	Відтворити ваш запис
Alt+c (compare/порівняти)	Відтворити ваш запис, потім оригінал
Alt+b (both/обидва)	Відтворити обидва накладеними — помилки створюють дисонанс
Alt+n (next/далі)	Завершити речення: скинути цикл, видалити створені файли, продовжити

Скидання циклу третім натисканням l також видаляє робочі файли, тож тримайте цикл встановленим, доки не завершите роботу з реченням.

Примітки

• Робочі файли зберігаються в системному тимчасовому каталозі і видаляються після скидання циклу.
• Якщо відносна гучність вашого голосу в накладенні/міксі звучить занадто тихо або занадто голосно порівняно з оригіналом, її можна відрегулювати, змінивши значення 3dB з [1:a]volume=3dB[r]; у функції overlay() на інше. Збільшення значення додасть гучності, зменшення її знизить.
• Зміни у скрипті набудуть чинності лише для нових екземплярів mpv, тобто може знадобитися перезапуск програми.