npm package: @labspc/asciiverse
Description: ![License](https://img.shields.io/badge/license-Apache-blue.svg) ![Version](https://img.shields.io/badge/version-0.9.0-green.svg)
Latest version: 0.9.2

# AsciiVerse - Media to ASCII Art Converter

![License](https://img.shields.io/badge/license-Apache-blue.svg)
![Version](https://img.shields.io/badge/version-0.9.0-green.svg)

[![NPM Version](https://img.shields.io/npm/v/@labspc/asciiverse.svg)](https://www.npmjs.com/package/@labspc/asciiverse)
[![NPM Downloads](https://img.shields.io/npm/dm/@labspc/asciiverse.svg)](https://www.npmjs.com/package/@labspc/asciiverse)

## 项目简介

**AsciiVerse** 是一个创新的Web应用程序，能够将媒体文件（如MP4视频）转换为富有艺术感的ASCII动画。通过将视频帧转换为ASCII字符艺术，创造出独特的视觉体验。本项目使用最新的Web技术栈，提供高性能的客户端媒体处理能力。


## 项目简介

**AsciiVerse** 是一个创新的Web应用程序，能够将图片和视频转换为富有艺术感的ASCII艺术作品。它支持多种媒体格式的转换，并提供实时预览功能，让用户能够即时查看转换效果。


### 在线演示
访问我们的 [在线演示](https://asciiverse.lamberts.space/) 体验AsciiVerse的功能。

- **视频处理**
  - 支持MP4视频上传和实时处理
  - 使用ffmpeg.wasm进行高效视频转换
  - 支持视频帧提取和分析
- **ASCII转换**
  - 支持彩色和灰度ASCII效果
  - 可自定义ASCII字符映射
  - 实时预览转换效果
- **性能优化**
  - 基于WebAssembly的高性能处理
  - 支持多线程并行处理
  - 内存优化的流式处理
- **用户体验**
  - 直观的拖放上传界面
  - 可调节播放参数（速度、大小等）
  - 支持导出ASCII动画为文件
  - 响应式设计，支持移动端

## ✨ 核心特性


- 🎥 支持视频转ASCII动画
  - MP4视频实时转换
  - 可调节帧率和分辨率
  - 支持暂停/播放控制
  
- 🖼️ 图片转ASCII艺术
  - 支持多种图片格式（PNG, JPG, GIF等）
  - 实时预览转换效果
  - 可调节字符密度和对比度

- 🎨 丰富的自定义选项
  - 支持彩色和灰度ASCII效果
  - 可自定义ASCII字符集
  - 多种输出样式选择

- 🚀 高性能处理
  - 基于WebAssembly的FFmpeg处理
  - 浏览器端本地处理，保护隐私
  - 支持大文件处理

## 🛠️ 技术栈

- **核心框架**: React 18 + TypeScript
- **状态管理**: React Context
- **路由系统**: React Router v6
- **视频处理**: @ffmpeg/ffmpeg + WebAssembly
- **UI组件**: 
  - Lucide React (图标)
  - TailwindCSS (样式)
- **开发工具**: 
  - Vite (构建工具)
  - ESLint + TypeScript (代码质量)
  - Swagger UI React (API文档)

## 🚀 快速开始

### 环境要求

- Node.js >= 18
- 现代浏览器（支持WebAssembly）

- Node.js 18+
- npm 9+ 或 yarn 1.22+

- npm 或 yarn

### 安装步骤

```bash
# 克隆项目
git clone https://github.com/labspc/asciiverse.git

# 进入项目目录
cd asciiverse

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

访问 `http://localhost:5173` 开始使用

## 在线演示

访问我们的在线演示网站体验 AsciiVerse 的功能：

🌐 [AsciiVerse - https://asciiverse.lamberts.space/](https://asciiverse.lamberts.space/)

在线演示支持以下功能：
- 视频转ASCII动画预览
- 实时参数调整
- 效果导出
- 移动端适配

## 技术栈

- **核心框架**: 
  - React 18.3.1
  - TypeScript 5.5.3
- **路由**: React Router DOM 6.22.0
- **媒体处理**: 
  - @ffmpeg/ffmpeg 0.12.10
  - @ffmpeg/util 0.12.1
- **UI组件**: 
  - Lucide React 0.344.0
  - TailwindCSS 3.4.1
- **工具链**: 
  - Vite 5.4.2
  - ESLint 9.9.1
- **文档**: Swagger UI React 5.11.0

## 项目结构

```
asciiverse/
├── src/
│   ├── api/           # API接口定义和实现
│   ├── components/    # 可复用的React组件
│   │   ├── common/    # 通用UI组件
│   │   └── media/     # 媒体处理相关组件
│   ├── context/       # React Context状态管理
│   ├── pages/         # 页面级组件
│   ├── styles/        # 全局样式和主题配置
│   ├── swagger/       # API文档配置
│   └── utils/         # 工具函数和常量
├── packages/          # 项目相关包
├── public/           # 静态资源
└── prompt/           # 提示词配置
```

## NPM包使用

AsciiVerse 提供了 NPM 包供开发者在自己的项目中使用：

```bash
# 使用 npm
npm install @labspc/asciiverse

# 使用 yarn
yarn add @labspc/asciiverse
```

### 基础使用示例

```typescript
import { AsciiConverter } from '@labspc/asciiverse';

// 创建转换器实例
const converter = new AsciiConverter({
  // 配置选项
  colorMode: 'color',  // 'color' 或 'grayscale'
  charset: 'default',  // ASCII字符集
  width: 80,          // 输出宽度
  height: 40          // 输出高度
});

// 转换视频
const result = await converter.convertVideo(videoFile, {
  fps: 30,            // 输出帧率
  quality: 'high'     // 输出质量
});
```

更多使用示例和API文档请访问：[NPM包文档](https://www.npmjs.com/package/@labspc/asciiverse)

## 开发

## 📦 项目结构

```
asciiverse/
├── src/                # 源代码目录
│   ├── api/           # API接口定义和实现
│   ├── components/    # 可复用React组件
│   ├── context/       # React Context状态管理
│   ├── pages/         # 页面级组件
│   ├── styles/        # 全局样式和主题
│   ├── swagger/       # API文档配置
│   └── utils/         # 工具函数和通用逻辑
├── public/            # 静态资源
└── prompt/            # AI提示配置
```

## 🔧 开发命令

```bash
# 开发环境
npm run dev

# 生产构建
npm run build

# 预览生产版本
npm run preview

# 代码检查
npm run lint
```

## 📝 开发规范

- 使用TypeScript进行严格的类型检查
- 遵循ESLint规则进行代码质量控制
- 使用Prettier进行代码格式化
- 遵循React最佳实践和Hooks规范
- 组件采用函数式编程范式

- 确保代码注释完整性



## 🤝 贡献指南

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交Pull Request

## 📋 开发计划

- [ ] 支持更多视频编码格式
- [ ] 添加AI辅助的ASCII艺术风格生成
- [ ] 优化WebAssembly性能
- [ ] 支持批量处理功能
- [ ] 添加社区分享功能
- [ ] 支持自定义字符映射规则
- [ ] 移动端适配优化

## 📄 开源协议

本项目采用 Apache 协议 - 查看 [LICENSE](LICENSE) 文件了解详情

## 👥 团队成员

- **Lambert** - *项目负责人* - [labspc](https://github.com/labspc)

## 📞 联系方式

- 项目仓库：[https://github.com/labspc/asciiverse](https://github.com/labspc/asciiverse)

- 问题反馈：[https://github.com/labspc/asciiverse/issues](https://github.com/labspc/asciiverse/issues)


- [ ] 支持更多视频格式（WebM、AVI等）
- [ ] 添加更多ASCII艺术风格和滤镜效果
- [ ] 优化WebAssembly性能和内存使用
- [ ] 添加批量处理功能
- [ ] 支持在线分享和社区功能
- [ ] 添加更多自定义选项
- [ ] 支持视频帧编辑功能

## 🙏 致谢

感谢所有为这个项目做出贡献的开发者！