osc-data 0.2.7

data represent, processing

osc-data

多模态数据表示与处理库，提供 Python 友好的 API 和 Rust 实现的高性能核心。

简介

osc-data 是一个用于多模态数据处理（文本、图像、音频、视频）的 Python 库，核心计算模块使用 Rust 实现以提供高性能。

特性

• 文本处理：流式句子分割，支持中英文混合文本
• 图像处理：加载、保存、格式转换、缩放、裁剪，支持 PNG/JPEG/WebP/BMP/GIF/TIFF
• 音频处理：音频加载、特征提取（分贝计算等）
• 视频处理：视频加载、帧提取、关键帧分割、保存
• 高性能：核心算法使用 Rust + PyO3 实现，Python 端使用 DocArray 类型系统

安装

环境要求

• Python >= 3.9
• Rust >= 1.70 (编译时需要，仅源码安装需要)

使用 pip 安装

# 从 PyPI 安装 
pip install osc-data

# 从 Git 仓库直接安装
pip install git+https://github.com/username/osc-data.git

# 安装指定版本
pip install osc-data==0.2.6

从源码安装

# 克隆仓库
git clone <repository-url>
cd osc-data

# 使用 uv 安装 (推荐)
uv sync

# 或使用 pip + maturin 构建
pip install maturin
maturin develop --release

# 或以可编辑模式安装
pip install -e .

快速开始

图像处理

from osc_data.image import Image

# 从本地或 URL 加载图片
img = Image(uri="./photo.jpg").load()
# img = Image(uri="https://example.com/image.png").load()

# 查看图片信息
print(f"尺寸: {img.width}x{img.height}, 格式: {img.format}")

# 格式转换
rgb_img = img.to_rgb()

# 缩放 (使用 Lanczos3 高质量算法)
small_img = img.resize(256, 256)

# 裁剪
cropped = img.crop(100, 100, 200, 200)

# 保存
img.save("output.png")
img.save("output.jpg", format="jpeg", quality=95)

# 批量处理
images = [img1, img2, img3]
resized_batch = Image.batch_resize_images(images, 256, 256)

文本流处理

from osc_data.text_stream import TextStreamSentencizer

sentencizer = TextStreamSentencizer()

# 流式处理文本
streaming_text = "你好！这是第一句话。这是第二句话。"

sentences = []
for char in streaming_text:
    sentences.extend(sentencizer.push(char))

# 输出剩余内容
sentences.extend(sentencizer.flush())

print(sentences)
# ['你好！', '这是第一句话。', '这是第二句话。']

视频处理

from osc_data.video import Video

# 加载视频
video = Video(uri="./video.mp4").load()

print(f"分辨率: {video.data.shape}, FPS: {video.fps}, 时长: {video.duration}s")

# 按关键帧分割
segments = video.split_by_key_frames(min_split_duration_s=5)

# 保存视频
video.save("output.mp4", format="mp4", codec="h264")

音频处理

from osc_data.audio import Audio

# 加载音频
audio = Audio(uri="./audio.wav").load()

print(f"采样率: {audio.sampling_rate}, 时长: {audio.duration}s")

# 计算分贝
from osc_data._core import compute_decibel
db = compute_decibel(audio.data, audio.sampling_rate)

API 文档

Image 类

方法	说明
load()	从本地路径或 URL 加载图片
save(path, format, quality)	保存图片到本地
to_rgb()	转换为 RGB 格式
resize(width, height)	缩放图片 (Lanczos3)
crop(x, y, width, height)	裁剪图片
to_bytes(format, quality)	转换为字节
from_bytes(data)	从字节创建图片
batch_resize_images(images, width, height)	批量缩放

TextStreamSentencizer 类

方法	说明
push(char)	推入单个字符，返回已完成的句子列表
flush()	清空缓冲区，返回剩余内容
reset()	重置状态

Video 类

方法	说明
load()	加载视频
split_by_key_frames(min_split_duration_s)	按关键帧分割
save(path, format, codec)	保存视频

项目结构

osc-data/
├── osc_data/           # Python 模块
│   ├── __init__.py
│   ├── image.py        # 图像处理
│   ├── video.py        # 视频处理
│   ├── audio.py        # 音频处理
│   ├── text.py         # 文本处理
│   ├── text_stream.py  # 流式文本分割
│   └── assets/         # 示例资源
│       ├── image/      # 示例图片
│       ├── audio/      # 示例音频
│       └── text/       # 示例文本
├── src/                # Rust 核心模块
│   ├── lib.rs          # 模块入口
│   ├── image.rs        # 图像处理核心
│   ├── audio.rs        # 音频处理核心
│   ├── text.rs         # 文本处理核心
│   └── text_stream.rs  # 流式文本分割核心
├── tests/              # 测试文件
│   ├── test_image.py
│   ├── test_sentencizer.py
│   └── ...
├── Cargo.toml          # Rust 配置
├── pyproject.toml      # Python 配置
└── README.md           # 本文件

开发

构建 Rust 扩展

maturin develop        # 开发模式 (快速编译)
maturin develop --release  # 发布模式 (优化)

运行测试

# 运行所有测试
pytest

# 运行特定模块测试
pytest tests/test_image.py -v
pytest tests/test_sentencizer.py -v

代码风格

# Python 代码格式化
ruff format osc_data/ tests/

# Rust 代码格式化
cargo fmt

依赖

Python 依赖

• pydantic >= 2.11.7: 数据验证
• docarray: 多模态数据类型系统
• numpy: 数组操作
• requests: HTTP 请求
• librosa >= 0.11.0: 音频处理
• av >= 10.0.0: 视频/音频编解码

Rust 依赖

• pyo3 >= 0.25.0: Python 绑定
• numpy: NumPy 数组操作
• ndarray: Rust 多维数组
• image >= 0.25.0: 图像处理
• regex: 正则表达式

作者

• wangmengdi - [e-mail]

License

[添加许可证信息]