Skip to content

About

A web-based studio for converting videos into customizable ASCII art reels with real-time rendering, timeline trimming, and audio-preserved export.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ASCII Reel Studio

一個純瀏覽器端執行的影片逐幀文字化(ASCII Art)轉換與播放工作室。使用者可直接匯入本地 MV 或任何影片(MP4 / MOV / WebM),即時將每一幀畫面轉換為按字元墨水密度排列的動態文字影像,同時完整保留原片音軌同步播放,並支援片段裁切與匯出標準 .mp4 影片。 image

主要功能

  • 即時逐幀 ASCII 渲染:透過離屏 Canvas 降採樣與 Glyph Atlas 墨水密度實測排序,支援原片比例與 Reel 9:16 面板(含幀數統計與捲動程式碼面板) 兩種版型。
  • 原片音軌同步保留:整合 Web Audio API 雙路音訊路由,播放與匯出過程皆可保留原片聲音,並支援原片子母畫面即時對照。
  • 自訂視覺與色彩參數:
    • 網格寬度(40–160 欄)與取樣幀率(24 / 30 / 60 fps)
    • 4 種字元密度表(經典 Reel 字元集、精細 68 階字元、半調方塊像素、二進位矩陣)
    • 4 種色彩著色模式(原片全彩、冷調銀藍、單色白光、終端綠光)
    • 對比度、亮度、Gamma 曲線、暗部星點閃爍(Starfield)與反轉明暗
  • 可收納右側參數抽屜:可由播放器旁隨時展開或收合參數面板,展開時底部與播放器保持水平對齊。
  • 播放器片段擷取與時間軸縮放:
    • 預設為簡潔的標準播放時間軸,點擊「擷取片段」可展開左右把手(In / Out Handles)調整起訖點、拖曳選取框整體平移範圍,並支援 Ctrl / Cmd + 滾輪 或滑桿縮放時間軸。
  • 全螢幕播放:播放器右下角提供純圖示全螢幕切換按鈕(滑鼠懸停顯示提示文字)。
  • 標準 MP4 匯出:優先採用瀏覽器原生 MP4 MediaRecorder,不支援時自動切換至 WebCodecs(H.264 + AAC)搭配 mp4-muxer 封裝輸出 .mp4。
  • 內建示範 MV:一鍵載入 NMIXX「긴 소원 (Birthday Wish)」示範影片。

技術棧

  • 前端框架:React 19 + TypeScript + Vite
  • 樣式系統:Tailwind CSS v4
  • 圖示庫:Lucide React
  • 音視訊與編碼:HTML5 Canvas 2D、Web Audio API、MediaRecorder API、WebCodecs API、mp4-muxer

專案結構

├── index.html                   # 入口 HTML 與字型設定
├── package.json                 # 相依套件與腳本
├── README.md                    # 專案說明文件
├── DOCS.md                      # 系統架構與技術說明文檔
└── src/
    ├── App.tsx                  # 主工作室介面、媒體控制與抽屜狀態管理
    ├── index.css                # Tailwind v4 全域樣式與自訂滑桿
    ├── types/
    │   └── ascii.ts             # 設定、幀統計與媒體資訊型別定義
    ├── components/
    │   ├── ControlPanel.tsx     # 右側可收納參數設定抽屜與 MP4 匯出區
    │   └── TrimTimeline.tsx     # 左右把手裁切與支援縮放的時間軸元件
    └── engine/
        ├── asciiEngine.ts       # Glyph Atlas 排序、亮度映射與畫布渲染核心
        └── mp4Exporter.ts       # MP4 錄製與 WebCodecs + mp4-muxer 封裝器

本機開發與建置

1. 安裝相依套件

npm install

2. 啟動開發伺服器

npm run dev

啟動後於瀏覽器開啟 http://localhost:3000。

3. 型別檢查與正式建置

npm run lint
npm run build

使用方式

  1. 點擊上方「上傳 MV 影片」或將影片拖放至主舞台(亦可點擊「載入內建示範 MV」立即體驗)。
  2. 在右側「轉換參數設定」抽屜調整網格欄數、幀率、字元集與色彩模式,或點擊播放器右上角「收合參數」獲得更大預覽空間。
  3. 若需裁切特定片段,點擊控制列中的「擷取片段」按鈕展開左右把手,拖曳起點/終點把手或選取框中央平移範圍,長影片可使用 Ctrl / Cmd + 滾輪 放大時間軸進行微調。
  4. 確認設定後,點擊右側抽屜底部的「匯出完整 MP4(含原音)」或「匯出片段 MP4(含原音)」,等待即時錄製封裝完成即可自動下載 .mp4 檔案。

GitHub Pages 自動部署

專案已內建 GitHub Actions 工作流程(.github/workflows/deploy.yml),會在推送程式碼至 main 或 master 分支時自動完成型別檢查、Vite 打包並發佈至 GitHub Pages:

  1. 將本專案推送至你的 GitHub Repository。
  2. 前往 GitHub Repository 的 Settings → Pages。
  3. 在 Build and deployment → Source 選擇 GitHub Actions。
  4. 之後每次 git push 至 main/master,或於 Actions 分頁手動執行 Deploy to GitHub Pages,即可自動更新線上網站(工作流程會自動偵測專案子路徑或自訂網域設定 VITE_BASE_PATH)。

About

A web-based studio for converting videos into customizable ASCII art reels with real-time rendering, timeline trimming, and audio-preserved export.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages