两行代码嵌入任意网站：ASCILINE官方JavaScript SDK与＜ascf-player＞组件API完全参考

两行代码嵌入任意网站：ASCILINE官方JavaScript SDK与 组件API完全参考

【免费下载链接】ASCILINEA high-performance ASCII video rendering engine featuring real-time WebSocket binary streaming and an isolated compiler for serverless static generation. Built for low-latency 30 FPS playback on HTML5 Canvas.项目地址: https://gitcode.com/gh_mirrors/as/ASCILINE

ASCILINE是一款高性能的实时 ASCII 视频渲染引擎，它将视频逐帧映射为字符网格，通过 WebSocket 二进制流推送，在 HTML5 Canvas 上以 30 FPS 流畅播放。本文将带你完整掌握其官方 JavaScript SDKasciline-player与零配置<ascf-player>Web 组件——只需两行代码，就能把这个文字视频播放器嵌入你的任何网站，支持直播 WebSocket 流与静态.ascf文件两种播放模式。

---

一、为什么选择 asciline-player？🚀

asciline-player是 ASCILINE 的官方客户端 SDK（MIT 协议），零依赖，提供两套互补的 API：

API	适用场景	难度
AsciiPlayer类	需要程序化控制的完整播放器	⭐⭐
<ascf-player>组件	纯 HTML 一行标签嵌入，无需写 JS	⭐

核心优势：

• 双模式播放：既能连接stream_server.py的实时 WebSocket 流，也能直接播放预编译的.ascf静态文件（无需任何后端）
• 完整播放控制：播放/暂停/静音/音量/滤镜/进度跳转，一应俱全
• 事件驱动：内置事件监听器 API，轻松对接你的业务逻辑
• 框架无关：原生 JS 即可运行，React/Vue 同样适用

核心源码位于 src/asciline-player.js（播放器引擎）与 src/ascf-element.js（Web 组件封装）。

---

二、最快上手：安装与两行代码示例

安装 SDK

npm install asciline-player

也可以在任意页面的<head>中直接引入 CDN 模块，跳过安装步骤。

两行代码嵌入播放器

<script type="module"> import { AsciiPlayer } from 'asciline-player'; const player = new AsciiPlayer('#ascii-canvas', { url: 'ws://localhost:8000/ws', playOverlay: true }); </script>

配合一个<canvas id="ascii-canvas">元素，播放器即自动接管渲染——自动创建 ▶ 播放按钮、静音开关，支持点击画面暂停、空格键切换播放。官方示例页 examples/quickstart.html 展示了带 FPS 徽标、像素模式切换与文字选择层的完整用法。

---

三、AsciiPlayer 类：构造函数选项完全参考

两种播放源

模式 A：实时 WebSocket 流（连接stream_server.py后端）

const player = new AsciiPlayer('#ascii-canvas', { url: 'ws://localhost:8000/ws', // 直播流地址 audio: true, // 启用同步音频 selectionLayer: true, // 可复制文字层 playOverlay: true, // 自动 ▶ 按钮 });

模式 B：静态.ascf文件（无需后端，可部署在任意静态托管）

const player = new AsciiPlayer('#ascii-canvas', { src: 'demo.ascf', // .ascf 文件 URL audioSrc: 'demo.mp3', // 可选的配套音频 loop: true, // 循环播放 }); // 或以命令式方式切换影片 player.play('demo.ascf', 'demo.mp3');

构造函数选项表

选项	默认值	说明
url	null	实时 WebSocket 流地址
src	null	静态.ascf文件 URL
audioSrc	null	与src配套的音频 URL
loop	false	静态文件播完后循环
audio	true	音频开关（布尔值 / 选择器 / HTMLAudioElement）
container	父元素	尺寸容器（元素或 CSS 选择器）
autoplay	false	立即开始播放
muted	false	初始静音
playOverlay	true	自动创建 ▶ 覆盖按钮
muteButton	true	自动创建静音切换按钮
clickToPlayPause	true	点击画面切换播放/暂停
keyboardShortcuts	true	空格键切换播放/暂停
selectionLayer	false	可复制文字覆盖层
bufferSize	4	抖动缓冲深度（帧数）
filters	{}	初始滤镜（对比度、伽马、亮度…）

完整默认值定义见 src/asciline-player.js。

---

四、编程式 API 与事件监听

播放控制方法

player.play('clip.ascf', 'clip.mp3'); // 静态文件 player.play(); // 直播流（使用 options.url） player.pause(); // 暂停 player.resume(); // 恢复 player.togglePlay(); // 切换 player.mute(); // 静音 player.unmute(); // 取消静音 player.setVolume(0.8); // 音量 0–1 player.setFilters({ contrast: 1.2, invert: true }); // 实时滤镜 player.setRenderMode(4); // 直播流：实时切换色彩深度 player.seek(30); // 直播流：跳转到第 30 秒 player.getMasterClock(); // 当前进度（秒） player.getState(); // 播放状态 player.destroy(); // 释放全部资源

⚠️ 两种模式共享相同的播放控制接口，仅setFilters与seek为 WebSocket 直播模式独有。

事件监听器 API

事件	回调参数	触发时机
init	{ fps, cols, rows, duration }	握手完成、网格信息就绪
timeupdate	seconds	播放进度更新
fps	{ fps, targetFps, buffered }	帧率指标上报
statechange	state	状态机变化
ended	—	播放结束
error	err	发生错误

player.on('statechange', (state) => console.log(state)); player.off('timeupdate', handler); // 移除监听

getState()返回的状态枚举为：IDLE|CONNECTING|PLAYING|PAUSED|ENDED|ERROR（定义见 src/asciline-player.js）。

---

五、 组件：一个标签搞定嵌入 🎬

如果你不想写一行 JavaScript，<ascf-player>自定义元素是最佳选择——加载一次脚本，之后在页面任意位置贴标签即可。

静态文件嵌入（推荐）

<!-- 页面中加载一次组件脚本（CDN 或本地） --> <script type="module" src="ascf-element.js"></script> <!-- 然后随处使用 --> <ascf-player src="demo.ascf" audio="demo.mp3" loop style="width:100%; aspect-ratio:16/9;"> </ascf-player>

直播流嵌入

将src换成ws属性即可连接实时流：

<ascf-player ws="ws://localhost:8000/ws" style="width:100%; aspect-ratio:16/9;"></ascf-player>

支持的 HTML 属性

属性	说明
src	.ascf文件 URL（静态模式必填）
audio	配套.mp3音频 URL（可选）
ws	WebSocket 直播地址（src的替代项）
autoplay	立即开始播放（布尔属性）
loop	播完自动重播（仅限src模式）
muted	初始静音（布尔属性，且支持运行时动态修改）

组件派发的 DOM 事件

所有AsciiPlayer事件会以ascf-前缀冒泡为 DOM CustomEvent，可直接用原生addEventListener捕获：

const el = document.querySelector('ascf-player'); el.addEventListener('ascf-playing', () => { /* 开始播放 */ }); el.addEventListener('ascf-ended', () => { /* 播放结束 */ }); el.addEventListener('ascf-timeupdate', (e) => { console.log(e.detail); // 当前时间（秒） });

完整事件列表：ascf-init、ascf-statechange、ascf-playing、ascf-paused、ascf-ended、ascf-error、ascf-timeupdate、ascf-fps、ascf-buffering（来源：src/ascf-element.js）。

组件直通方法（Pass-through API）

获取元素后可直接调用，行为与AsciiPlayer一致：

el.play(src, audio); // 开始/恢复播放，可传入新源 el.pause(); // 暂停 el.togglePlay(); // 切换 el.mute(); // 静音 el.unmute(); // 取消静音 el.setVolume(0.6); // 设音量 el.currentTime; // 当前进度（秒） el.duration; // 总时长（秒） el.playerState; // 状态字符串 el.player; // 直接访问底层 AsciiPlayer 实例

方法定义见 src/ascf-element.js。

---

六、React 等框架集成小贴士

在 React 中，只需在useEffect中创建播放器、卸载时调用destroy()即可，官方已提供参考组件 examples/react-quickstart.jsx：

useEffect(() => { const player = new AsciiPlayer(canvasRef.current, { url, autoplay }); player.on('statechange', (s) => setState(s)); return () => player.destroy(); // 组件卸载时清理资源 }, [url]);

---

七、常见问题速查 💡

问题	解决方案
静态模式播放无声音	检查audioSrc/audio属性是否指向可跨域访问的.mp3
直播流连接失败	确认后端已运行：python stream_server.py video.mp4（见 stream_server.py）
想编译静态.ascf文件	使用 Python 编译器：python compiler.py video.mp4 --cols 250 --pixel，源码见 compiler.py
卸载页面后内存未释放	务必调用player.destroy()或移除<ascf-player>元素（组件会在disconnectedCallback中自动清理）

---

八、相关文件索引

• SDK 入口与导出说明：package.json、src/index.js
• 播放器引擎（MIT 协议）：src/asciline-player.js
• <ascf-player>组件：src/ascf-element.js
• 原生 JS 快速示例：examples/quickstart.html
• React 参考组件：examples/react-quickstart.jsx
• SDK 导入测试：test/test_sdk_import.js
• 双协议许可说明：LICENSE-MIT（SDK）、LICENSE-AGPL（核心引擎）

asciline-player遵循 MIT 开源协议，可自由商用。两行代码，即可让 ASCII 视频流成为你网站的"文字显示器"——无论是直播 WebSocket 流还是静态.ascf文件，都能即插即用。

【免费下载链接】ASCILINEA high-performance ASCII video rendering engine featuring real-time WebSocket binary streaming and an isolated compiler for serverless static generation. Built for low-latency 30 FPS playback on HTML5 Canvas.项目地址: https://gitcode.com/gh_mirrors/as/ASCILINE