callesnikov-ascii-video-fork
Work with the local AI-assisted fork of https://github.com/stepanussaruran/ASCII-Video-Player for terminal ASCII video playback, color ASCII image conversion, and saving ASCII images/videos. Use when
SKILL.mdcallesnikov-ascii-video-fork/SKILL.md
GitHubCallesnikov ASCII Video Fork
Layout
Use this skill directory as a two-part project:
repository/: original upstream clone ofhttps://github.com/stepanussaruran/ASCII-Video-Player.fork/: Codex-made fork layer with added tools, dependencies, and PowerShell color helper.fork/java-swing/: simple Swing GUI wrapper that calls the fork Python script.fork/LICENSE.md: root MIT license file for standard GitHub license detection.fork/README.md: README for publishing the fork folder as an independent GitHub repository.fork/README-EN.md: English README translation for GitHub publishing.fork/licences/: bilingual MIT license and ethical attribution notices for the fork layer.README.md: user-facing Russian instructions. Keep it aligned with this file.
Do not mix new fork files into repository/ unless the user explicitly asks to patch the upstream player itself. Put additions in fork/.
For GitHub publishing, prefer making fork/ the repository root. Do not commit the nested repository/ clone into the published fork unless the user explicitly wants a monorepo/archive layout. The fork tools do not require repository/ at runtime; they only need files inside fork/ plus Python/Java dependencies.
The fork layer is licensed under MIT via fork/licences/LICENSE-EN.md and fork/licences/LICENSE-RU.md. The notices in fork/licences/NOTICE-EN.md and fork/licences/NOTICE-RU.md explain attribution to the original public repository and clarify that the license applies only to code/documentation created for this fork layer. Do not imply that this project relicenses upstream code.
Session Start
Before using the skill in a new session:
- Enter the skill directory.
- Confirm
repository/.gitexists. If it is missing, clone upstream intorepository/. - Check original repo status with
git status --short --branchfromrepository/. - Check upstream with
git fetch originwhen permissions allow it. - Only run
git pull --ff-onlywhen the worktree is clean and a fast-forward is possible. - If local changes exist, or if
.git/FETCH_HEADis not writable in the sandbox, do not repair destructively. Use the local clone and tell the user that upstream freshness could not be verified or applied.
Never delete the local copy if upstream disappears.
Dependencies
For original video playback:
cd repository
python -m pip install -r ../fork/requirements.txt
For fork tools:
cd fork
python -m pip install -r requirements.txt
fork/requirements.txt includes opencv-python, numpy, and pillow.
Notes:
- Image conversion needs
numpyandpillow. - Video preview/saving needs
opencv-python. - If dependency installation is blocked, still run syntax checks and image checks when available; explain that full video testing requires OpenCV.
Ask The User
For conversion requests, collect only missing essentials:
- input media path;
- image vs video when extension is ambiguous;
- ASCII width in characters, usually
80,120, or180; - optional ASCII height in rows;
- color or monochrome;
- desired output: terminal preview, text file, PNG, MP4, or text frames;
- output path when saving;
- optional rendered pixel size such as
1280x720. - vivid look preference: use
--vivid, or tune--brightness,--contrast,--saturation,--gamma, and--glow.
Use fork/ascii_outputs/ by default for generated fork outputs.
Supported input formats:
- Images:
.jpg,.jpeg,.png,.bmp,.webp,.tif,.tiff. - Videos:
.mp4,.avi,.mkv,.mov,.webm.
Saved output formats:
- Rendered ASCII images:
.png. - ASCII image text:
.txt. - Rendered ASCII videos:
.mp4. - ASCII video frames:
.txtfiles in a directory.
Original Player
Use repository/ASCII_v4_ultimate.py for the upstream video terminal player.
cd repository
python ASCII_v4_ultimate.py path/to/video.mp4 --info
python ASCII_v4_ultimate.py path/to/video.mp4 --width 150
python ASCII_v4_ultimate.py path/to/video.mp4 --color --width 100
python ASCII_v4_ultimate.py path/to/video.mp4 --color --skip 2 --loop
Arguments:
video: video file path.--color: ANSI 24-bit color playback.--no-color: monochrome playback.--width: terminal ASCII width.--skip: render every Nth frame for performance.--loop: repeat playback until interrupted.--info: print video metadata without playback.
Fork Media Tool
Use fork/ascii_media_tools.py for photos, saved outputs, and rendered ASCII videos.
Image Preview
cd fork
python ascii_media_tools.py image path/to/photo.jpg --width 120 --print
python ascii_media_tools.py image path/to/photo.jpg --width 120 --color --print
If no save option is provided, the image command prints to the terminal.
Save Image Text
cd fork
python ascii_media_tools.py image path/to/photo.jpg --width 120 --save-text ascii_outputs/photo.txt
python ascii_media_tools.py image path/to/photo.jpg --width 120 --color --save-text ascii_outputs/photo_ansi.txt
Use --color for ANSI-colored text files. Omit it for plain text.
Save Rendered Image
cd fork
python ascii_media_tools.py image path/to/photo.jpg --width 140 --save-image ascii_outputs/photo_ascii.png
python ascii_media_tools.py image path/to/photo.jpg --width 140 --color --save-image ascii_outputs/photo_color_ascii.png
python ascii_media_tools.py image path/to/photo.jpg --width 140 --color --vivid --save-image ascii_outputs/photo_vivid.png
python ascii_media_tools.py image path/to/photo.jpg --width 180 --color --brightness 1.2 --contrast 1.55 --saturation 2.1 --gamma 1.25 --glow 1.4 --save-image ascii_outputs/photo_glow.png
python ascii_media_tools.py image path/to/photo.jpg --width 160 --output-size 1280x720 --color --save-image ascii_outputs/photo_1280x720.png
Resolution rules:
--widthis ASCII columns.--heightis ASCII rows. If omitted, the source aspect ratio is preserved with terminal-friendly character proportions.--output-size WIDTHxHEIGHTresizes rendered PNG/MP4 to exact pixel dimensions.--cell-width,--cell-height,--font-size,--font-path, and--thicknesstune rendered output.--vividapplies a bright, saturated, high-contrast preset.- Default fork output is intentionally brighter than neutral: brightness
1.12, contrast1.25, saturation1.35, gamma1.12, glow0.6. --brightness,--contrast,--saturation, and--gammatune the source before ASCII conversion.--glowadds a soft glow to saved PNG/MP4 outputs; it does not affect plain terminal text.--vividstacks on top of the brighter defaults for an extra bright, saturated look.
Video Preview
cd fork
python ascii_media_tools.py video path/to/video.mp4 --preview --width 100
python ascii_media_tools.py video path/to/video.mp4 --preview --width 80 --color --skip 2
For pure playback, prefer the original player. Use this command when the same tool must also save outputs.
Save Rendered Video
cd fork
python ascii_media_tools.py video path/to/video.mp4 --width 120 --save-video ascii_outputs/video_ascii.mp4
python ascii_media_tools.py video path/to/video.mp4 --width 100 --color --skip 2 --save-video ascii_outputs/video_color_ascii.mp4
python ascii_media_tools.py video path/to/video.mp4 --width 100 --color --vivid --skip 2 --save-video ascii_outputs/video_vivid.mp4
python ascii_media_tools.py video path/to/video.mp4 --width 160 --output-size 1280x720 --fps 24 --color --save-video ascii_outputs/video_1280x720.mp4
Video notes:
--skip Nrenders every Nth source frame.- Default output FPS is
source_fps / skip; use--fpsto override. --max-frames Nis useful for quick tests.- Default codec is
--fourcc mp4v.
Save Text Frames
cd fork
python ascii_media_tools.py video path/to/video.mp4 --width 100 --save-frames ascii_outputs/frames
python ascii_media_tools.py video path/to/video.mp4 --width 100 --color --save-frames ascii_outputs/color_frames
Color Terminal Output
Color output is possible with ANSI 24-bit escape codes.
Best environments:
- Windows Terminal with PowerShell 7 or modern Windows PowerShell.
- VS Code terminal.
- iTerm2, Alacritty, and other modern terminals on macOS/Linux.
Less reliable:
- old classic Windows Console windows;
- redirected logs;
- Codex sandbox terminal display for live video previews.
The Python scripts call Windows console ANSI enabling where possible. The fork also includes a PowerShell helper:
cd fork
.\run_color_preview.ps1 -InputPath "C:\path\photo.jpg" -Width 120
.\run_color_preview.ps1 -InputPath "C:\path\video.mp4" -Width 90
Inside Codex, prefer saving color PNG/MP4 for reliable verification. For live colorful TikTok-style terminal previews, recommend Windows Terminal.
Java Swing Wrapper
Use fork/java-swing/ when the user wants a double-clickable GUI.
Current GUI behavior:
src/AsciiPhotoSwingApp.javaopens a Swing window.- The UI is in English with a light "forge/media victim" tone.
- The tiny
...button chooses an image or video file. Forge by widthruns normal processing throughascii_media_tools.py ... --color --vivid.Forge at native sizereads the original pixel size and passes--output-size WIDTHxHEIGHT.Stop the forgeterminates the current Python process.- Progress bar consumes
PROGRESS current total percentlines fromascii_media_tools.py --progress. - Width defaults to
160and is editable. - Output is written as
ascii_outputs/photo_ascii_yyyyMMdd_HHmmss.pngorascii_outputs/video_ascii_yyyyMMdd_HHmmss.mp4. - The app checks
ASCII_FORK_PYTHON; if unset, it runspython.
Natural size means original rendered pixel dimensions, not one ASCII character per source pixel. Keep ASCII width as the detail control. For videos, natural size detection requires OpenCV in Python.
Build:
cd fork\java-swing
.\build.ps1
Run:
.\run_gui.ps1
Double-click option:
fork\java-swing\run_gui.bat
The built JAR is:
fork\java-swing\dist\AsciiPhotoSwingApp.jar
JVM packaging notes:
- Do not say the JVM is embedded into a JAR. A JAR still needs Java installed and associated with
.jar, unless launched via script. - For a self-contained Windows app, use
jpackage, which bundles a Java runtime beside the app. - Run
fork\java-swing\package_windows.ps1when a full JDK withjpackageis available. - If only
java/javacare available, deliverrun_gui.batand the JAR. jpackagebundles Java only. It does not bundle Python or OpenCV/Pillow. If the user wants a truly no-dependency desktop app, add a separate Python runtime packaging step later.
Validation
After edits:
cd fork
python -m py_compile ascii_media_tools.py
python ascii_media_tools.py --help
python ascii_media_tools.py image path/to/photo.jpg --width 48 --save-text ascii_outputs/test.txt --save-image ascii_outputs/test.png
python ascii_media_tools.py video path/to/video.mp4 --width 80 --max-frames 5 --save-video ascii_outputs/test.mp4
cd java-swing
.\build.ps1
If OpenCV is missing, video commands should fail with a clear install message instead of a traceback.
Maintenance
- Keep README.md, README-EN.md, licence notices, and SKILL.md consistent when changing commands or publication guidance.
- Keep upstream code in
repository/clean unless directly patching the original player. - Put new fork scripts, wrappers, and requirements in
fork/. - Avoid destructive Git operations. Never reset or checkout away local work unless the user explicitly asks.