#Quickstart

From nothing to a running stream. Everything here uses a local video file.

#Requirements

Python 3.9+
FFmpeg and FFprobe, needed for audio and hover thumbnails
Any modern browser with Canvas and WebSocket support

Install FFmpeg with your package manager:

winget install ffmpeg      # Windows
brew install ffmpeg        # macOS
sudo apt install ffmpeg    # Linux

#Install

git clone https://github.com/YusufB5/ASCILINE.git
cd ASCILINE
pip install .

#Stream a video

python stream_server.py video.mp4 --mode 6 --cols 160

Open http://localhost:8000/. Click Play, and enable audio if the browser asks for a gesture.

--mode picks the color depth (1 = monochrome, 6 = 16.7M colors) and --cols sets the grid width. Every flag is listed in the Live streaming reference.

#Try pixel mode with the DCT codec

Pixel mode draws colored blocks instead of characters. The optional DCT codec shrinks it dramatically:

python stream_server.py video.mp4 --pixel --pixel-codec dct --cols 320

DCT is lossy and applies only to pixel mode. For higher grids and 60 FPS there is an optional Rust engine; see How it works.

#Use your webcam

python stream_server.py --webcam --cols 240

#Compile a clip for static hosting

No server at playback time:

python compiler.py your_video.mp4 --cols 250 --pixel --quantize 2

This produces an .ascf file. See the Static player page to play it.

#Embed it in a page

<script type="module" src="./src/ascf-element.js"></script>

<ascf-player src="clip.ascf" audio="clip.mp3" loop
  style="width:100%; aspect-ratio:16/9"></ascf-player>

For a live stream use ws="ws://localhost:8000/ws" instead of src.

Published package vs. repository. Check which version of asciline-player you installed: releases from before synchronized live playback and live pixel DCT don't have them and fall back to raw pixels. When in doubt, use the src/ folder from the repository. The SDK reference explains the difference.

#Next

Read How it works for the pipeline, or jump to the JavaScript SDK to control playback from code.