Skip to main content
The phichain-renderer is a headless rendering tool that converts Phichain projects into video files. It uses the same game engine as the playable version to ensure accuracy.

​
Installation

The renderer requires FFmpeg to be installed on your system: 
sudo apt install ffmpeg
Then build the renderer: 
cargo build --release -p phichain-renderer

​
Usage

​
Basic Syntax

phichain-renderer <PATH> [OPTIONS]

​
Arguments

​
path
string
required
The path to the Phichain project directory (not the chart file).
​
--output
string
default:"output.mp4"
The path where the output video will be saved.
​
--from
float
default:"0.0"
The start time of the chart to render in seconds. Defaults to the beginning.
​
--to
float
The end time of the chart to render in seconds. Defaults to the music duration.

​
Video Options

​
--width
integer
default:"1920"
The width of the output video in pixels.
​
--height
integer
default:"1080"
The height of the output video in pixels.
​
--fps
integer
default:"60"
The frame rate of the output video.

​
Game Options

Customize the visual appearance of the rendered chart:
​
--note-scale
float
default:"1.0"
Scale factor for notes. Values above 1.0 make notes larger, below 1.0 make them smaller.
​
--fc-ap-indicator
boolean
default:"false"
Enable the FC/AP indicator. Since the renderer uses autoplay, this will always show a perfect score.
​
--no-multi-highlight
boolean
default:"false"
Disable multi-hit highlight effects for notes.
​
--hide-hit-effect
boolean
default:"false"
Hide the visual effects when notes are hit.
​
--name
string
Override the chart name displayed in the video.
​
--level
string
Override the difficulty level displayed in the video.

​
Examples

​
Basic Rendering

Render a complete chart with default settings: 
phichain-renderer ./my-chart-project
Output: output.mp4 (1920x1080, 60fps)

​
Custom Output Path

phichain-renderer ./my-chart --output renders/my-chart.mp4

​
Render Specific Section

Render only a portion of the chart (e.g., from 30 seconds to 90 seconds): 
phichain-renderer ./my-chart --from 30.0 --to 90.0 --output preview.mp4

​
4K Resolution

phichain-renderer ./my-chart --width 3840 --height 2160 --output 4k-render.mp4

​
Custom Game Settings

phichain-renderer ./my-chart \
  --note-scale 1.2 \
  --hide-hit-effect \
  --no-multi-highlight \
  --output clean-render.mp4

​
Override Chart Metadata

phichain-renderer ./my-chart \
  --name "My Custom Chart" \
  --level "SP Lv.15" \
  --output final-version.mp4

​
Performance

The renderer displays real-time performance information during rendering: 
100 / 3600 (2.78%), 45fps (0.75x), estimate to end 133.33s
200 / 3600 (5.56%), 52fps (0.87x), estimate to end 114.29s
300 / 3600 (8.33%), 58fps (0.97x), estimate to end 95.24s
Performance metrics are updated every 100 frames. The estimate to end shows the approximate remaining time based on current rendering speed.

​
Performance Information

  • Frame Progress - Current frame / Total frames
  • Percentage - Completion percentage
  • FPS - Current rendering speed in frames per second
  • Multiplier - Speed relative to target FPS (e.g., 1.0x means real-time)
  • Estimate - Estimated time remaining in seconds

​
Output Format

The renderer outputs H.264 encoded MP4 files using FFmpeg:
  • Video codec: libx264
  • Pixel format: RGBA (converted to H.264)
  • No audio: The renderer only outputs video (you’ll need to add audio separately)
The renderer does not include audio in the output video. You’ll need to merge the audio track separately using FFmpeg or video editing software.

​
Adding Audio to Rendered Video

ffmpeg -i output.mp4 -i music.mp3 -c copy -map 0:v:0 -map 1:a:0 final.mp4

​
Rendering Pipeline

The renderer works by:
  1. Loading - Load the Phichain project and chart data
  2. Setup - Initialize the game engine and rendering pipeline
  3. Pre-roll - Render 40 frames to warm up (not saved)
  4. Capture - Render each frame and pipe to FFmpeg
  5. Encode - FFmpeg encodes frames to H.264 video
  6. Complete - Display total render time

​
Tips

  • Hardware acceleration: The renderer uses GPU acceleration when available
  • Render time: Expect rendering to take 1-2x the chart duration on modern hardware
  • Memory usage: Higher resolutions and FPS require more memory
  • Batch rendering: Use shell scripts to render multiple charts automatically

​
Batch Rendering Example

#!/bin/bash
for project in projects/*; do
  name=$(basename "$project")
  phichain-renderer "$project" --output "renders/${name}.mp4"
done

​
Common Issues

​
FFmpeg Not Found

Failed to spawn ffmpeg
Solution: Install FFmpeg and ensure it’s in your PATH.

​
Low Performance

If rendering is very slow:
  • Try lowering the resolution (--width 1280 --height 720)
  • Reduce FPS (--fps 30)
  • Close other GPU-intensive applications

​
Memory Errors

For very long charts or high resolutions, you may encounter memory issues. Try:
  • Rendering in segments using --from and --to
  • Reducing resolution temporarily
  • Increasing system swap/page file size

​
See Also