--- name: build-batch-video-sync-checker description: Build a command line tool that checks a whole folder of videos for audio and lip-sync problems and writes a report. Use it when someone has many recordings and cannot check each one by eye. license: CC BY 4.0. Free to use and share with credit to technologytips.blog. metadata: publisher: technologytips.blog article: https://technologytips.blog/articles/check-video-audio-sync-automatically/ article_title: "Out-of-sync audio in hundreds of videos? Build a checker" published: 2026-11-12 platforms: [mac, windows, linux] needs: [claude-code] risk: medium version: 1 sha256: pending --- # Build a batch video sync checker *An AI Fix file from technologytips.blog. Give this file to your AI assistant and say: "Read this file, then walk me through it one step at a time." It works on your own computer, and it asks before anything that can't be undone.* ## What this fixes You have many recorded videos, and some have a voice that does not match the lips. Checking each by eye is not realistic. This file helps you build a tool that checks the whole folder and writes a report. It will not promise a perfect reading on every clip, and it never changes your original videos. ## Read this first (safety) - Never ask me to paste a password, recovery code, secret key, 2FA code or private key into this chat. If a step needs one, tell me to type it only into the official app or website. - Before any step that deletes, overwrites, signs out, resets or uninstalls anything, stop, tell me exactly what will happen, and wait for me to say yes. - Make or confirm a backup before changing anything you can't undo. - Only use official apps, official download pages and official documentation. Never suggest cracked software, unofficial installers or scripts from unknown sources. - Never turn off a security feature (encryption, 2FA, firewall, antivirus, FileVault, BitLocker) permanently. If a fix needs it off for a moment, say so and turn it back on. - If anything looks different from these steps, stop and tell me instead of guessing. - This file is general help, not professional support. For account recovery, the company that runs the account is the only real authority. - Never write to an original video. Fixed files go to a new folder, and the originals stay as they are. - Treat footage and transcripts as personal data. Keep outputs next to the footage and out of public repositories. This file is marked medium risk. The tool only reads videos, but a careless repair step could overwrite a file you cannot replace. ## What you need - A Mac, Windows or Linux computer, with about 1 GB of free disk for the sync model environment, plus room for the videos. - A few hours for a first working version. Less if you stop after the checker. - Node 16 or newer (only for the editing side), Python 3.11 or newer, and ffmpeg. Install each from its official page or a package manager named in its official docs. - A terminal and Claude Code or Codex installed from the official page: https://code.claude.com/docs/en/overview. Start it in a plain, empty folder, not your home folder, and use the approval mode that asks first. See /start-here/ on technologytips.blog. - A folder of sample videos, including one you already know is off. ## Instructions for the AI You are helping one person build one tool on their own computer, using only the steps and sources in this file. Be kind and patient. Say it is not their fault. Go one step at a time and wait for them to say it is done. Read every command aloud in plain words before they run it. Never run a command that deletes, overwrites, moves, signs out, resets or uninstalls without their yes. If your answer would differ from this file, say so and ask. Say "as of November 2026" when you give a version, because versions change. If something does not match what they see, stop and help them describe it, word for word. ## Questions to ask first Ask these a few at a time, in plain words. If the answer changes the steps, say how. 1. What kind of videos are they: talking heads, call recordings, AI avatar clips, or something else? 2. Which computer and operating system do you use, and are Python, ffmpeg and Node already installed? 3. Do you also want the editing side (cuts, captions, rendering), or only the checker? 4. Do you have a clip you know is out of sync, and can you point me to a folder of samples? ## Steps 1. **Confirm a backup.** Ask whether the footage is copied somewhere safe. Wait for a yes before any later step touches a file. The tool only reads, but later repair steps write copies. 2. **Scaffold the tool.** Create a Python package with one command, `sync `. It walks the folder, pulls out the audio, and samples several time windows per video. Ffprobe, as of November 2026, prints facts about each stream in a readable form. 3. **Check the setup.** In one plain sentence, tell the reader this command prints stream facts for one sample video and changes nothing. ``` ffprobe -hide_banner sample.mp4 ``` 4. **Add a lip-sync model for faces.** Choose a published lip-sync network, and read its official page first. Pin its downloaded weights by SHA-256 checksum, and keep its Python environment outside any cloud-synced folder. 5. **Add a fallback for clips without faces.** Use audio-to-video cross-correlation. Trust it only when two or more windows agree. Otherwise report "unmeasurable". 6. **Write the verdicts.** Use pass, drift, step, review and unmeasurable. Save results as JSON lines, plus an HTML report and a CSV. 7. **Make it resumable.** Keep a per-file cache so a long run can stop and restart. 8. **Test with shifts you made.** Copy a good clip into a new folder. Delay the copy's audio by known amounts (asks before running, because it writes a new file). Confirm the checker reads the delays back within a few milliseconds. 9. **Run it on the real folder.** Run `sync` on the sample folder first. Read the report together. Wait for the reader to say what looks right before running on everything. 10. **Optional: build the editing side.** Describe each cut in one small file, in seconds, with frame math in whole frames. In Remotion, a video's first frame is 0 and its last is durationInFrames minus 1, as of November 2026. Add word timings with Whisper if they want cut-by-transcript. Gate every render with the sync checker, and do loudness after the render, not inside it. ## How to check it worked - A clip you delayed on purpose shows up as off, and the size matches what you set. - A clip you know is fine shows as pass. - Stop and rerun the tool, and confirm it skips files it already did. - Name the small win: the checker works. Then tell them the time they got back and nudge them to spend it on someone or something they love. ## If something goes wrong - A reading is "unmeasurable". That is honest. It usually means no face and no sharp sounds. Review that clip by ear. - Readings disagree between the two checks on a talking head. Trust the lip model for faces, and use the second check only for sharp events. - A gap grows over time. It may be drift. Check each person's own audio track, because tracks can have different offsets. - A voice sounds unclear after a fix. Check whether the edit used a poor call-audio copy or a track that picked up another voice, before blaming the tool. - If you are stuck or unsure, stop. Do not retry the same step over and over. Use the official docs for Remotion, ffprobe and Claude Code (see Sources). ## Never do this - Never overwrite an original video. - Never paste a secret into this chat. Read-only tokens go only into the tool's own settings. - Never run a command you do not understand. Ask me to explain it first. - Never use an unofficial download, a cracked app, or a script from a forum. ## Sources 1. Remotion. "The core idea." Official docs page, same as the article's source 1. Checked November 12, 2026. 2. Remotion. "Licensing." Official pricing page, same as the article's source 2. Checked November 12, 2026. 3. OpenAI (Whisper project). "openai/whisper." https://github.com/openai/whisper. Checked November 12, 2026. 4. FFmpeg. "ffprobe Documentation." Official documentation, same as the article's source 4. Checked November 12, 2026. 5. Anthropic. "Overview, Claude Code Docs." https://code.claude.com/docs/en/overview. Checked November 12, 2026. 6. Remotion. "Creating a new project." Official docs home, same as the article's source 6. Checked November 12, 2026. ## About this file Made by technologytips.blog from the article https://technologytips.blog/articles/check-video-audio-sync-automatically/, checked against its sources on November 12, 2026. Written with AI, checked against the article and security-scanned. General help, not professional support. Menus, prices and rules change: check the official page before you rely on a step. Free to use and share with credit to technologytips.blog (CC BY 4.0).