DYER2JZ RACE HIGHLIGHTS 1.2.0 =========================== A native desktop tool for finding and editing short moments inside long racing recordings. Import a file or paste a completed YouTube livestream link. Recordings are downloaded to your PC and edited locally. There is no account, subscription, web server or video upload service. WINDOWS: START HERE ------------------ 1. Extract this ENTIRE ZIP to a normal folder, such as Documents\RaceHighlights. Do not launch it from inside the ZIP viewer. 2. Run Setup_Windows.bat once. It installs missing Python, FFmpeg, yt-dlp, Deno and Tesseract through Windows Package Manager (WinGet). Python/video/ download tools use current-user setup; Tesseract's Windows installer may request administrator access. First setup needs internet access and accepts those packages' installation agreements. 3. Run Start_Race_Highlights.bat or the desktop shortcut to open the window. 4. Click Import video, or paste your finished stream's Share link into the YouTube live replay box and click Download & edit. 5. Use Set up race HUD for event scans. Select the position and speed digits, then Test reading, Save HUD areas and click Find racing moments. 6. Review candidates and export. 4K vertical output is selected by default. This download contains the working desktop application and setup/launch files. It is a Python desktop package, not a precompiled standalone .exe installer. Python 3.10 or newer with Tcl/Tk, plus FFmpeg/ffprobe, must be installed. Windows setup uses separate yt-dlp and Deno executables for YouTube importing. The editor itself uses the Python standard library; no pip install is needed with the Windows setup route. PASTE A YOUTUBE LIVESTREAM LINK ------------------------------ 1. Open the finished stream's video in YouTube and copy its Share link. 2. Use the YouTube live replay box near the top of the app. Click Paste or press Ctrl+V into the box. Normal watch, /live/ and youtu.be links work. 3. Choose 720p, 1080p, 1440p, 2160p (4K, default) or Best available. This limits source resolution; a 4K choice does not upscale a smaller video. Lower source resolution reduces download size and later processing work. 4. Download folder chooses where the full recording will be saved. Default: your home folder\Videos\DYER2JZ_Race_Highlights\YouTube. 5. Click Download & edit. Video/audio download progress is shown separately; the percentage may restart when the next stream begins. After merging and checking the file, the recording opens in the existing editor automatically. 6. Click Find racing moments, or enter a known timestamp and click Add moment. Set up the HUD for racing event scans, or use an activity profile. Trim, title, frame and export selected 2160x3840 (4K) MP4 short clips. The importer downloads the full finished recording before editing. A 1-3 hour stream can require considerable download time and disk space. Each import gets its own folder, with source.mkv (or another supported video container) and a source_info.json note containing the original link, title and selected quality. Keep the downloaded source if you save a project. It is not a temporary file. Cancel stops the download and its child processes, and removes only that new unfinished download folder. Existing projects and downloads are kept. Supported: a single public or unlisted finished video or processed live replay. Streams still running, scheduled streams and replays still processing must wait until the completed replay is available. Channel and playlist links are not supported. The importer does not access your signed-in browser or cookies. For a private or login-required replay, download your own video from YouTube Studio first and use Import video. YouTube can reject automated downloads; availability, account restrictions or server-side changes may block a link. If a finished public replay fails, close the app, run Update_YouTube_Tools.bat, then reopen the app and try again. That script updates only yt-dlp and Deno through WinGet. Manually installed/bundled tools need manual updates instead. See the final troubleshooting section for manual setup and exact-file links. OVERTAKES AND CRASH CANDIDATES ----------------------------- The default profile is Overtakes + crashes (HUD). It reads the current race position and speed from the recording, and uses them as event evidence. 1. Import the recording. Click Set up race HUD. 2. Choose a timestamp while racing with the HUD visible, then Load frame. 3. Select Draw position and drag a tight rectangle around the current position NUMBER only. For P4/16, select only 4; exclude P and /16. 4. Select Draw speed and drag around the speed NUMBER only. Exclude km/h or mph, RPM, gear and surrounding digits. Select the correct speed units. 5. Leave White digits on a dark HUD ticked for a typical white-on-dark game HUD. Untick for dark digits on a light panel. Use Test reading and compare the decoded position/speed to the displayed frame. Adjust the areas if needed. 6. Save HUD areas. Choose Overtakes + crashes, Overtakes / position gains, or Crashes / sudden stops, then click Find racing moments. Only position is needed for overtake candidates; only speed for crash candidates. Selecting both gives the scanner more context. Save project retains these areas and the export resolution. A new recording starts with unconfigured areas. The HUD location must stay consistent for the recording. Recalibrate if the camera layout, source resolution, stream border or overlay position changes. Possible overtakes: a smaller position number held for at least two consecutive one-second readings, with a stable prior position. It suppresses isolated OCR flicker, very large jumps, long unreadable gaps and stationary changes when speed can be read. This can also flag positions gained during opponents' pit stops, retirements or penalties; those require manual review. Possible crashes / sudden stops: speed at least 80 km/h drops at least 70 km/h in about two seconds, stays at or below 45 km/h for two readings, and a local sound spike or visual disruption supports it. Plain slowing, steady engine noise and brightness changes alone do not qualify. Heavy braking can still create false candidates. A speed glitch with only one bad reading is suppressed. Each candidate includes its evidence and footage before the timestamp (default 8-second lead-in). Clips remain reviewable, trimmable and removable. The rank measures evidence strength; it is not an event probability. Nearby overlapping candidates are deduplicated so the same moment is not repeatedly exported. The reader samples once per second and needs legible digits. It cannot prove an actual pass or collision, detect lapped-car passes without position changes, or identify an opponent's crash that leaves your speed unaffected. Brief passes, spins without a major slowdown, occluded HUDs, menus and changing layouts may be missed or misread. No car/object model or commentary transcription is included. When HUD digits are unavailable, select a general activity profile or add a known moment by timestamp. A failed scan leaves the prior candidate list intact. Event scans read the HUD from decoded frames even when Fast scan is ticked. Fast/Detailed affects the general visual impact/activity cues. HUD decoding and OCR add work, so event scans of long high-resolution recordings can take time. Images are processed in small batches; no video or digit readings are uploaded. FIND THE BEST CANDIDATES ------------------------ * Recordings of one, two and three hours are supported. There is no three-hour cutoff. MP4, MKV, MOV, WEBM and other formats supported by your FFmpeg build can be imported. Use a completed, seekable recording with a known duration. * Max clips: 1-40 suggestions. Default: up to 8 clips. * Clip seconds: 3-60 seconds. Default: 30. * Lead-in seconds: footage before the activity peak. Default: 8 seconds. It must be shorter than the clip. Leave enough context before an incident. * General activity profiles remain available below the three HUD event profiles. * Race action combines sound changes and increased visual activity. * Commentary / sound spikes gives more weight to louder bursts. * Visual activity uses motion/change signals, including silent recordings. * Fast scan uses keyframes and samples one small frame per second. It is quicker for typical compressed recordings but can miss brief moments, especially when keyframes are far apart. Untick it for Detailed scan. * Detailed scan decodes all video frames, then analyses one per second. It takes longer and can also miss very short events between samples. HOW THE SUGGESTIONS WORK ----------------------- The general activity profiles measure audio energy relative to the recording and visual changes relative to the recording's usual activity. It reduces the importance of uniform brightness flashes and abrupt camera cuts. Steady engine noise alone is not a highlight signal. It ranks activity peaks and avoids selecting overlapping clips. The rank is signal strength out of 100, NOT a probability that an overtake or incident occurred. Those profiles do not identify specific race events. The HUD event profiles described above add position/speed evidence. The app has no car/object recognition, race-win detection, speech transcription or automatic captions. Camera changes, menus and loud music can still receive a high score. Quiet but excellent race moments can be missed. Always review the suggestions and add your own timestamps for missed moments. The scanner reads small video/audio chunks. It stores one set of measurements per second rather than the full decoded recording. Scan speed depends on duration, resolution, codec, storage and CPU; the app does not promise instant analysis or a fixed completion time for real racing footage. REVIEW, TRIM AND FRAME --------------------- 1. Select a suggested clip from the list. Scrub inside its proposed start/end using the slider to inspect source frames. 2. Edit start/end as seconds, MM:SS or HH:MM:SS. Decimals are supported. You can also use Set start/end at frame. Manual trims can be 0.5-180 seconds. 3. Enter an optional headline (up to 80 characters, rendered over the video). 4. Choose one of the three 9:16 layouts: Full race + blurred background: keeps the complete race view and HUD, with blurred video filling the portrait frame. This is the default. Vertical crop: fills the portrait frame; drag the turquoise crop guide to choose the visible part. Framing is fixed per clip, without auto-tracking. Full race + black background: keeps the complete race view, with black space. 5. Click Apply trim / title, or Render & play preview. The preview is an actual 360x640 MP4 opened in your computer's default video player. The frame viewer itself displays the source image and crop guide, not live video playback. 6. Use the checkbox, space key or double-click to include/exclude a clip. Use all / Clear ticks affect the full list. Remove deletes only a suggestion. Click the full-recording activity timeline to inspect an arbitrary timestamp. The timestamp appears in the Add moment field; click Add moment to create a manual candidate. You can also type any timestamp you know. Both the moments panel and review panel scroll vertically on smaller screens. Use their scrollbars or the mouse wheel over the source frame/background area. EXPORT FOR SHORTS / TIKTOK ------------------------- Click Export selected clips and choose a parent folder. Each run creates a new Race_Highlights__ subfolder. Outputs: 2160 x 3840 (4K, default) or 1080 x 1920, 9:16 portrait, MP4, H.264 video, yuv420p, AAC stereo audio when the source has sound. Choose 24, 30 or 60 FPS. Default: 30 FPS. 60 FPS does not create true additional motion from a lower-frame-rate source. Source audio is retained, with very short fades at the clip boundaries. There is no replacement music, speech transcription or publishing integration. 4K encodes use CRF 18, Lanczos foreground scaling and 320 kb/s AAC stereo. 1080p uses CRF 20 and 192 kb/s AAC stereo. These are quality targets, not a fixed video bitrate. 4K files generally use more disk space and take longer to encode. The playable review preview stays at 360x640 for speed; exports use the chosen resolution. Clip manifests record the actual output and source dimensions. The Brand field defaults to DYER2JZ and is burned near the bottom. Clear it for unbranded clips. A headline is burned near the top. Rendering a preview lets you check both against your racing HUD before the final export. Increasing output resolution cannot add detail missing from the source. Choose a 4K source download when available for the best starting material. HDR-to-SDR tone mapping is not implemented; SDR recordings are recommended. clip_manifest.json accompanies each export, recording source timestamps, clip titles, layouts, framing and completion status. Cancel stops processing, removes the unfinished clip and keeps already completed clips. Open exports opens the destination folder. Upload the MP4s yourself when ready. Your source video is opened for reading and is never intentionally replaced. Existing clips are not overwritten. Exporting uses free disk space; an output folder must be writable. Closing during a task cancels it and waits for cleanup. SAVE YOUR WORK -------------- Save project writes a .racecuts.json file containing the source location, suggestions, event labels/evidence, ranking timeline, trim edits, titles, framing, HUD areas, export resolution and app settings. Open project restores them. The project does NOT contain a copy of your video. Keep the original recording. If it moves, the app can relink a recording with matching size, duration and dimensions. If the content changed, scan it again. This version cannot resume an unfinished scan. A cancelled scan can be rerun; your prior candidate list is kept until a new scan finishes. MANUAL WINDOWS SETUP / TROUBLESHOOTING -------------------------------------- If WinGet is missing, install Microsoft's App Installer or use manual setup. Install a current Python 3 from https://www.python.org/downloads/windows/ Include Tcl/Tk and the Python launcher. Choose Add Python to PATH when offered. Get a Windows FFmpeg build linked from: https://ffmpeg.org/download.html#build-windows Place ffmpeg.exe AND ffprobe.exe in this app's tools\bin folder. Use the same distribution for both, with libx264, AAC and drawtext support. Its own licensing and source notices apply. FFmpeg binaries are not redistributed in this ZIP. For manual YouTube importing, also place official yt-dlp.exe and deno.exe in tools\bin (or on PATH): https://github.com/yt-dlp/yt-dlp/releases/latest https://github.com/denoland/deno/releases/latest Use the official Windows yt-dlp standalone executable, which includes its matching EJS component. Deno 2.3+ is recommended. Node 22+ on PATH is also supported by the importer if Deno is unavailable. Install the current releases. Third-party downloader builds may lack YouTube's JavaScript support. For manual HUD event detection, install Tesseract with English data: https://tesseract-ocr.github.io/tessdoc/Installation.html https://github.com/UB-Mannheim/tesseract/wiki The app finds tesseract.exe on PATH or in the normal Tesseract-OCR install folders. A full portable distribution may be placed in tools\bin, including its DLLs and tessdata\eng.traineddata. Copying the EXE alone is insufficient. Setup_Event_Detection.bat installs the OCR engine and checks English data. It can be run separately when other editing/download tools are already present. Setup installs Python.Python.3.13, Gyan.FFmpeg, yt-dlp.yt-dlp, DenoLand.Deno and tesseract-ocr.tesseract only if missing. It does not automatically update installed versions. Reopen the app after setup finishes. If setup cannot find new executables, close/reopen your terminal or restart Windows. Extract assets alongside the scripts so the bundled font is available. Missing moov atom / invalid data usually means an incomplete or damaged recording. The default player must support MP4 playback for preview. Close preview windows before exiting the app to allow temporary preview files to be removed. Last processing error: %LOCALAPPDATA%\DYER2JZ_Race_Highlights\last_error.log. MAC / LINUX ----------- Install Python 3.10+, Tkinter and FFmpeg/ffprobe using your system's normal installer/package manager. Run python3 race_highlights.py from this folder, or use Start_Mac_Linux.sh. Windows setup scripts apply to Windows only. For YouTube, install current yt-dlp with matching EJS using: python3 -m pip install -U "yt-dlp[default]" Also install Deno 2.3+ or Node 22+ using the official instructions: https://docs.deno.com/runtime/getting_started/installation/ https://nodejs.org/en/download If pip packages are installed into an externally managed Python, use your normal virtual environment and run the editor with that environment's Python. Update the same yt-dlp[default] package and runtime when extraction breaks. For HUD event detection, also install Tesseract plus its English language data using your operating system's package manager (for example Homebrew tesseract, or Linux tesseract-ocr and tesseract-ocr-eng). No Python OCR package is required. OPTIONAL COMMAND LINE --------------------- python race_cli.py check python race_cli.py check --youtube python race_cli.py check --events python race_cli.py youtube "YOUR_VIDEO_SHARE_LINK" --output "Downloads" --quality 1080p python race_cli.py scan "my race.mp4" --project "my.racecuts.json" python race_cli.py scan "my race.mp4" --project "my.racecuts.json" --detailed python race_cli.py scan "my race.mp4" --profile events --hud-config "saved.racecuts.json" --project "events.racecuts.json" python race_cli.py export "my.racecuts.json" --output "Exports" --fps 30 python race_cli.py export "my.racecuts.json" --output "Exports" --resolution 1080p CLI export defaults to 4K. HUD config accepts a saved project's HUD settings, or a JSON file containing position/speed regions and speed units. The desktop app can open projects created by the command line. VALIDATION AND INCLUDED SAMPLE ------------------------------ Demo/Synthetic_Signal_Test.mp4 is a generated test pattern, not racing footage. It contains two louder/more active sections. Import it with clip length 15, lead-in 4 and Commentary / sound spikes to try the app's workflow. Engine checks: python -m unittest discover -s tests -v Long-file check: python tools/validate_long_recording.py TEST_RESULTS.txt reports the actual checks run for this release. The app's native Windows window and WinGet setup must be checked on a Windows computer; this package was built and its media engine tested in Linux. YouTube importer integration tests use a simulated downloader with real local video, FFmpeg analysis and MP4 export. No actual YouTube video was downloaded in this build environment. See TEST_RESULTS.txt for the checks and limitations. Event integration tests use a generated HUD recording with two scripted position gains and one scripted speed collapse plus sound spike. Real OCR detects those controlled changes. Real 2160x3840 files were encoded in all three layouts. Real race footage was not supplied, so event accuracy on racing is unmeasured. Technical references used for implementation: https://ffmpeg.org/ffmpeg.html https://ffmpeg.org/ffmpeg-filters.html https://docs.python.org/3/library/tkinter.html https://learn.microsoft.com/en-us/windows/package-manager/winget/install https://github.com/yt-dlp/yt-dlp https://github.com/yt-dlp/yt-dlp/wiki/EJS https://docs.deno.com/runtime/getting_started/installation/ https://tesseract-ocr.github.io/tessdoc/Command-Line-Usage.html https://tesseract-ocr.github.io/tessdoc/ImproveQuality.html Bundled DejaVu Sans Bold licence: assets/DejaVu_License.txt.