CosyVoice命令行工具开发快速语音合成的Python脚本实战最近在做一个自动化内容生成的项目需要把大量文本转成语音。一开始我都是手动调用CosyVoice的API每次改个参数都要重新写代码效率实在太低。后来我想为什么不写个命令行工具呢就像平时用的git、pip那样一条命令就能搞定语音合成。今天我就来分享这个实战经验教你从零开始写一个轻量级的CosyVoice命令行工具。这个工具能让你从文件或直接输入文本生成语音指定输出格式和保存路径批量处理多个文本文件实时显示进度方便集成到自动化脚本即使你Python基础一般跟着做下来也能掌握命令行工具开发的核心技巧。咱们不搞复杂的架构设计就解决实际问题让你写出来的工具马上就能用。1. 环境准备与项目搭建在开始写代码之前我们先准备好开发环境。这个工具主要依赖两个库argparse处理命令行参数tqdm显示进度条。1.1 安装必要依赖打开终端创建一个新的项目目录然后安装需要的包# 创建项目目录 mkdir cosyvoice-cli cd cosyvoice-cli # 创建虚拟环境推荐 python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # Mac/Linux: source venv/bin/activate # 安装核心依赖 pip install argparse tqdm # 安装CosyVoice SDK根据官方文档选择合适版本 pip install cosyvoice-sdk如果你用的是Anaconda也可以用conda创建环境conda create -n cosyvoice-cli python3.9 conda activate cosyvoice-cli pip install argparse tqdm cosyvoice-sdk1.2 项目结构规划一个好的项目结构能让代码更清晰也方便后期维护。我建议这样组织文件cosyvoice-cli/ ├── cosyvoice_cli/ │ ├── __init__.py │ ├── cli.py # 命令行入口 │ ├── core.py # 核心合成逻辑 │ └── utils.py # 工具函数 ├── requirements.txt # 依赖列表 ├── setup.py # 安装配置 └── README.md # 使用说明先创建这些基础文件# 创建目录结构 mkdir -p cosyvoice_cli touch cosyvoice_cli/__init__.py touch cosyvoice_cli/cli.py touch cosyvoice_cli/core.py touch cosyvoice_cli/utils.py touch requirements.txt touch setup.py touch README.md在requirements.txt里写上依赖argparse1.4.0 tqdm4.65.0 cosyvoice-sdk1.0.0这样基础环境就准备好了。接下来我们开始写核心功能。2. 核心合成功能实现我们先从最核心的语音合成功能开始。这部分代码会放在core.py里负责调用CosyVoice的API。2.1 基础合成函数打开cosyvoice_cli/core.py我们先写一个最简单的合成函数import os from pathlib import Path from typing import Optional, Union class CosyVoiceSynthesizer: CosyVoice语音合成器 def __init__(self, api_key: Optional[str] None): 初始化合成器 Args: api_key: CosyVoice API密钥如果为None则尝试从环境变量读取 self.api_key api_key or os.getenv(COSYVOICE_API_KEY) if not self.api_key: raise ValueError(未提供API密钥请通过参数或环境变量COSYVOICE_API_KEY设置) # 这里根据CosyVoice SDK的实际API进行调整 # 假设SDK的初始化方式如下 from cosyvoice import CosyVoiceClient self.client CosyVoiceClient(api_keyself.api_key) def synthesize( self, text: str, output_path: Union[str, Path], voice_type: str standard, speed: float 1.0, format: str mp3 ) - bool: 将文本合成为语音文件 Args: text: 要合成的文本 output_path: 输出文件路径 voice_type: 音色类型 speed: 语速0.5-2.0 format: 输出格式mp3/wav Returns: bool: 合成是否成功 try: # 确保输出目录存在 output_dir os.path.dirname(output_path) if output_dir: os.makedirs(output_dir, exist_okTrue) # 调用CosyVoice API # 这里根据实际SDK调整调用方式 audio_data self.client.synthesize( texttext, voicevoice_type, speedspeed, formatformat ) # 保存音频文件 with open(output_path, wb) as f: f.write(audio_data) print(f✓ 合成成功: {output_path}) return True except Exception as e: print(f✗ 合成失败: {str(e)}) return False这个类封装了基本的合成功能。我加了详细的参数说明和错误处理这样用起来更放心。2.2 批量处理功能很多时候我们需要一次处理多个文件比如把一本电子书分成多个章节转成音频。我们来添加批量处理功能from tqdm import tqdm from typing import List class BatchProcessor: 批量处理器 def __init__(self, synthesizer: CosyVoiceSynthesizer): self.synthesizer synthesizer def process_files( self, input_files: List[str], output_dir: str, voice_type: str standard, format: str mp3 ): 批量处理多个文本文件 Args: input_files: 输入文件列表 output_dir: 输出目录 voice_type: 音色类型 format: 输出格式 if not os.path.exists(output_dir): os.makedirs(output_dir) success_count 0 total_count len(input_files) print(f开始批量处理 {total_count} 个文件...) # 使用tqdm显示进度条 for input_file in tqdm(input_files, desc处理进度): try: # 读取文本内容 with open(input_file, r, encodingutf-8) as f: text f.read().strip() if not text: print(f警告: {input_file} 为空文件跳过) continue # 生成输出文件名 base_name os.path.splitext(os.path.basename(input_file))[0] output_file os.path.join(output_dir, f{base_name}.{format}) # 合成语音 if self.synthesizer.synthesize( texttext, output_pathoutput_file, voice_typevoice_type, formatformat ): success_count 1 except Exception as e: print(f处理文件 {input_file} 时出错: {str(e)}) print(f\n批量处理完成成功: {success_count}/{total_count})批量处理功能加上了进度条处理大量文件时能清楚看到进度不会让人干等着。3. 命令行接口设计核心功能写好了现在来设计命令行接口。我们用argparse库来解析命令行参数。3.1 基础参数解析打开cosyvoice_cli/cli.py先写参数解析部分import argparse import sys from pathlib import Path from typing import List def parse_arguments(): 解析命令行参数 parser argparse.ArgumentParser( descriptionCosyVoice命令行工具 - 快速语音合成, formatter_classargparse.RawDescriptionHelpFormatter, epilog 使用示例: # 从文本生成语音 cosyvoice-cli -t 你好世界 -o hello.mp3 # 从文件生成语音 cosyvoice-cli -f input.txt -o output.mp3 # 批量处理多个文件 cosyvoice-cli -b file1.txt file2.txt -d outputs/ # 指定音色和语速 cosyvoice-cli -t 测试文本 -o test.wav --voice female --speed 1.2 ) # 输入方式组互斥 input_group parser.add_mutually_exclusive_group(requiredTrue) input_group.add_argument( -t, --text, help直接输入要合成的文本 ) input_group.add_argument( -f, --file, help从文件读取文本 ) input_group.add_argument( -b, --batch, nargs, help批量处理多个文件 ) # 输出参数 parser.add_argument( -o, --output, requiredTrue, help输出文件路径单文件或目录批量 ) # 音频参数 parser.add_argument( --voice, defaultstandard, choices[standard, female, male, child], help音色类型默认: standard ) parser.add_argument( --speed, typefloat, default1.0, help语速0.5-2.0默认: 1.0 ) parser.add_argument( --format, defaultmp3, choices[mp3, wav, ogg], help输出格式默认: mp3 ) # 其他参数 parser.add_argument( --api-key, helpCosyVoice API密钥也可通过环境变量COSYVOICE_API_KEY设置 ) parser.add_argument( --verbose, actionstore_true, help显示详细日志 ) return parser.parse_args()我设计了三种输入方式直接输入文本、从文件读取、批量处理多个文件。这样能满足不同场景的需求。3.2 主函数实现参数解析写好了现在来实现主函数把各个部分连接起来def main(): 命令行工具主函数 # 解析参数 args parse_arguments() # 初始化合成器 from .core import CosyVoiceSynthesizer try: synthesizer CosyVoiceSynthesizer(api_keyargs.api_key) except ValueError as e: print(f初始化失败: {e}) print(请设置API密钥) print( 1. 通过 --api-key 参数) print( 2. 或设置环境变量 COSYVOICE_API_KEY) sys.exit(1) # 根据输入方式处理 if args.text: # 直接输入文本 handle_text_input(synthesizer, args) elif args.file: # 从文件读取 handle_file_input(synthesizer, args) elif args.batch: # 批量处理 handle_batch_input(synthesizer, args) print(任务完成) def handle_text_input(synthesizer, args): 处理直接文本输入 if args.verbose: print(f合成文本: {args.text[:50]}...) print(f输出文件: {args.output}) success synthesizer.synthesize( textargs.text, output_pathargs.output, voice_typeargs.voice, speedargs.speed, formatargs.format ) if not success: sys.exit(1) def handle_file_input(synthesizer, args): 处理文件输入 try: with open(args.file, r, encodingutf-8) as f: text f.read() if args.verbose: print(f从文件读取: {args.file}) print(f文本长度: {len(text)} 字符) success synthesizer.synthesize( texttext, output_pathargs.output, voice_typeargs.voice, speedargs.speed, formatargs.format ) if not success: sys.exit(1) except FileNotFoundError: print(f错误: 文件不存在 {args.file}) sys.exit(1) except Exception as e: print(f读取文件失败: {str(e)}) sys.exit(1) def handle_batch_input(synthesizer, args): 处理批量输入 from .core import BatchProcessor processor BatchProcessor(synthesizer) # 检查输出路径是否为目录 output_dir args.output if not os.path.isdir(output_dir): print(f错误: 批量处理时输出路径必须是目录) print(f请创建目录: mkdir -p {output_dir}) sys.exit(1) processor.process_files( input_filesargs.batch, output_diroutput_dir, voice_typeargs.voice, formatargs.format ) if __name__ __main__: main()主函数根据不同的输入方式调用对应的处理函数逻辑很清晰。错误处理也考虑得比较周全。4. 打包与安装配置工具写好了我们还要让它能像其他命令行工具一样方便安装和使用。4.1 编写setup.py创建setup.py文件这是Python包的安装配置文件from setuptools import setup, find_packages with open(README.md, r, encodingutf-8) as fh: long_description fh.read() setup( namecosyvoice-cli, version0.1.0, authorYour Name, author_emailyour.emailexample.com, description命令行工具 for CosyVoice语音合成, long_descriptionlong_description, long_description_content_typetext/markdown, urlhttps://github.com/yourusername/cosyvoice-cli, packagesfind_packages(), classifiers[ Programming Language :: Python :: 3, Programming Language :: Python :: 3.7, Programming Language :: Python :: 3.8, Programming Language :: Python :: 3.9, License :: OSI Approved :: MIT License, Operating System :: OS Independent, ], python_requires3.7, install_requires[ argparse1.4.0, tqdm4.65.0, # CosyVoice SDK根据实际情况添加 ], entry_points{ console_scripts: [ cosyvoice-clicosyvoice_cli.cli:main, ], }, )关键在entry_points部分它告诉Python安装后创建一个叫cosyvoice-cli的命令。4.2 安装和使用现在可以安装我们的工具了# 开发模式安装可编辑 pip install -e . # 或者普通安装 pip install .安装后就可以在命令行使用了# 查看帮助 cosyvoice-cli --help # 测试简单合成 cosyvoice-cli -t 这是一个测试 -o test.mp3 # 从文件合成 cosyvoice-cli -f novel_chapter1.txt -o chapter1.mp3 --voice female # 批量处理 cosyvoice-cli -b chapter*.txt -d audio_chapters/ --format wav4.3 编写使用说明一个好的工具要有清晰的文档。在README.md里写上使用说明# CosyVoice命令行工具 一个轻量级的命令行工具用于快速调用CosyVoice语音合成服务。 ## 功能特性 - 支持文本直接输入、文件读取、批量处理 - 多种音色选择标准、女声、男声、童声 - ⚡ 可调节语速0.5x-2.0x - 支持MP3、WAV、OGG格式输出 - 批量处理显示进度条 ## 快速开始 1. 安装 bash pip install cosyvoice-cli设置API密钥export COSYVOICE_API_KEYyour-api-key-here使用示例# 简单合成 cosyvoice-cli -t 你好世界 -o hello.mp3 # 从文件合成 cosyvoice-cli -f input.txt -o output.wav --voice female # 批量处理 cosyvoice-cli -b file1.txt file2.txt -d outputs/详细参数查看完整参数说明cosyvoice-cli --help集成到脚本可以在Shell脚本中调用#!/bin/bash for chapter in chapters/*.txt; do base$(basename $chapter .txt) cosyvoice-cli -f $chapter -o audio/${base}.mp3 done## 5. 实用技巧与进阶功能 基础功能已经完成了但要让工具更好用还需要一些实用技巧。 ### 5.1 添加配置文件支持 每次都输API密钥挺麻烦的我们可以添加配置文件支持 python # 在utils.py中添加 import json import os from pathlib import Path def get_config_dir(): 获取配置目录 home Path.home() config_dir home / .config / cosyvoice config_dir.mkdir(parentsTrue, exist_okTrue) return config_dir def load_config(): 加载配置文件 config_file get_config_dir() / config.json if config_file.exists(): with open(config_file, r) as f: return json.load(f) return {} def save_config(config): 保存配置文件 config_file get_config_dir() / config.json with open(config_file, w) as f: json.dump(config, f, indent2) def set_api_key(api_key): 设置API密钥到配置文件 config load_config() config[api_key] api_key save_config(config) print(API密钥已保存到配置文件)然后在命令行工具里添加配置命令# 在cli.py的parse_arguments中添加子命令 subparsers parser.add_subparsers(destcommand, help子命令) # 配置命令 config_parser subparsers.add_parser(config, help配置管理) config_parser.add_argument(--set-api-key, help设置API密钥) # 在main函数中处理子命令 if args.command config: if args.set_api_key: from .utils import set_api_key set_api_key(args.set_api_key) else: from .utils import load_config config load_config() print(当前配置:) for key, value in config.items(): print(f {key}: {value}) return这样用户就可以用cosyvoice-cli config --set-api-key your-key来保存密钥了。5.2 添加格式转换功能有时候我们需要在不同格式间转换可以添加这个功能# 在core.py中添加 import subprocess from pathlib import Path class AudioConverter: 音频格式转换器 staticmethod def convert_format(input_file: str, output_file: str, target_format: str): 转换音频格式需要安装ffmpeg Args: input_file: 输入文件 output_file: 输出文件 target_format: 目标格式 try: # 检查ffmpeg是否安装 subprocess.run([ffmpeg, -version], capture_outputTrue, checkTrue) except (subprocess.CalledProcessError, FileNotFoundError): print(错误: 需要安装ffmpeg才能进行格式转换) print(安装方法: https://ffmpeg.org/download.html) return False # 构建转换命令 cmd [ ffmpeg, -i, input_file, -y, # 覆盖输出文件 output_file ] try: subprocess.run(cmd, capture_outputTrue, checkTrue) print(f✓ 格式转换成功: {output_file}) return True except subprocess.CalledProcessError as e: print(f✗ 格式转换失败: {e.stderr.decode()}) return False5.3 错误处理优化好的错误提示能让用户更快解决问题。我们优化一下错误处理# 在core.py的synthesize方法中添加更详细的错误处理 def synthesize(self, text: str, output_path: str, **kwargs) - bool: 增强版的合成方法 # 参数验证 if not text or not text.strip(): print(错误: 文本内容不能为空) return False if len(text) 5000: # 假设API限制 print(警告: 文本过长建议分割成多段) # 可以在这里添加自动分割逻辑 # 检查输出路径 output_path Path(output_path) if output_path.exists(): print(f警告: 文件已存在 {output_path}) # 可以询问是否覆盖这里简单跳过 return False # 检查目录权限 output_dir output_path.parent if not os.access(output_dir, os.W_OK): print(f错误: 没有写入权限 {output_dir}) return False # 原来的合成逻辑...6. 常见问题与解决在实际使用中可能会遇到一些问题。这里整理了几个常见问题和解决方法。问题1API密钥错误错误: 认证失败请检查API密钥解决方法检查密钥是否正确cosyvoice-cli config查看当前配置重新设置cosyvoice-cli config --set-api-key 新密钥检查环境变量echo $COSYVOICE_API_KEY问题2文本过长CosyVoice可能有文本长度限制如果遇到错误可以分割文本# 在utils.py中添加文本分割函数 def split_long_text(text, max_length1000): 将长文本分割成多段 paragraphs text.split(\n) chunks [] current_chunk for para in paragraphs: if len(current_chunk) len(para) 1 max_length: current_chunk para \n else: if current_chunk: chunks.append(current_chunk.strip()) current_chunk para \n if current_chunk: chunks.append(current_chunk.strip()) return chunks问题3网络连接问题如果API调用超时或失败可以添加重试机制import time from functools import wraps def retry_on_failure(max_retries3, delay1): 失败重试装饰器 def decorator(func): wraps(func) def wrapper(*args, **kwargs): for attempt in range(max_retries): try: return func(*args, **kwargs) except Exception as e: if attempt max_retries - 1: raise print(f尝试 {attempt 1} 失败{delay}秒后重试...) time.sleep(delay) return None return wrapper return decorator # 使用装饰器 retry_on_failure(max_retries3, delay2) def synthesize_with_retry(self, text, output_path): # 原来的合成逻辑 pass问题4内存不足处理大量文件时可能内存不足可以优化文件处理方式def process_large_files(self, file_list, output_dir): 处理大文件的优化版本 for input_file in file_list: # 逐行读取大文件 with open(input_file, r, encodingutf-8) as f: chunk [] chunk_size 0 for line in f: chunk.append(line) chunk_size len(line) # 达到一定大小就处理 if chunk_size 1000: # 每1000字符处理一次 text .join(chunk) # 合成这一块 # ... chunk [] chunk_size 0 # 处理剩余部分 if chunk: text .join(chunk) # 合成 # ...7. 总结写这个CosyVoice命令行工具的过程其实也是学习Python工程化开发的好机会。从最开始的简单脚本到后来加入参数解析、错误处理、配置文件、批量处理等功能工具变得越来越实用。用下来感觉最大的好处是效率提升。以前要写一堆代码才能完成的工作现在一行命令就搞定了。批量处理功能特别实用处理几十个文件也不用一直盯着。如果你刚开始接触命令行工具开发建议先从简单的功能开始然后逐步添加需要的特性。不用追求一次完美先让工具跑起来再慢慢优化。遇到问题就查文档、看错误信息大部分问题都能找到解决方法。这个工具还有很多可以扩展的地方比如添加更多音频效果选项、支持流式合成、集成到其他工作流中等等。你可以根据自己的需求来定制。关键是要让工具真正解决实际问题而不是为了写工具而写工具。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
CosyVoice命令行工具开发：快速语音合成的Python脚本实战
发布时间：2026/7/7 22:43:25
CosyVoice命令行工具开发快速语音合成的Python脚本实战最近在做一个自动化内容生成的项目需要把大量文本转成语音。一开始我都是手动调用CosyVoice的API每次改个参数都要重新写代码效率实在太低。后来我想为什么不写个命令行工具呢就像平时用的git、pip那样一条命令就能搞定语音合成。今天我就来分享这个实战经验教你从零开始写一个轻量级的CosyVoice命令行工具。这个工具能让你从文件或直接输入文本生成语音指定输出格式和保存路径批量处理多个文本文件实时显示进度方便集成到自动化脚本即使你Python基础一般跟着做下来也能掌握命令行工具开发的核心技巧。咱们不搞复杂的架构设计就解决实际问题让你写出来的工具马上就能用。1. 环境准备与项目搭建在开始写代码之前我们先准备好开发环境。这个工具主要依赖两个库argparse处理命令行参数tqdm显示进度条。1.1 安装必要依赖打开终端创建一个新的项目目录然后安装需要的包# 创建项目目录 mkdir cosyvoice-cli cd cosyvoice-cli # 创建虚拟环境推荐 python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # Mac/Linux: source venv/bin/activate # 安装核心依赖 pip install argparse tqdm # 安装CosyVoice SDK根据官方文档选择合适版本 pip install cosyvoice-sdk如果你用的是Anaconda也可以用conda创建环境conda create -n cosyvoice-cli python3.9 conda activate cosyvoice-cli pip install argparse tqdm cosyvoice-sdk1.2 项目结构规划一个好的项目结构能让代码更清晰也方便后期维护。我建议这样组织文件cosyvoice-cli/ ├── cosyvoice_cli/ │ ├── __init__.py │ ├── cli.py # 命令行入口 │ ├── core.py # 核心合成逻辑 │ └── utils.py # 工具函数 ├── requirements.txt # 依赖列表 ├── setup.py # 安装配置 └── README.md # 使用说明先创建这些基础文件# 创建目录结构 mkdir -p cosyvoice_cli touch cosyvoice_cli/__init__.py touch cosyvoice_cli/cli.py touch cosyvoice_cli/core.py touch cosyvoice_cli/utils.py touch requirements.txt touch setup.py touch README.md在requirements.txt里写上依赖argparse1.4.0 tqdm4.65.0 cosyvoice-sdk1.0.0这样基础环境就准备好了。接下来我们开始写核心功能。2. 核心合成功能实现我们先从最核心的语音合成功能开始。这部分代码会放在core.py里负责调用CosyVoice的API。2.1 基础合成函数打开cosyvoice_cli/core.py我们先写一个最简单的合成函数import os from pathlib import Path from typing import Optional, Union class CosyVoiceSynthesizer: CosyVoice语音合成器 def __init__(self, api_key: Optional[str] None): 初始化合成器 Args: api_key: CosyVoice API密钥如果为None则尝试从环境变量读取 self.api_key api_key or os.getenv(COSYVOICE_API_KEY) if not self.api_key: raise ValueError(未提供API密钥请通过参数或环境变量COSYVOICE_API_KEY设置) # 这里根据CosyVoice SDK的实际API进行调整 # 假设SDK的初始化方式如下 from cosyvoice import CosyVoiceClient self.client CosyVoiceClient(api_keyself.api_key) def synthesize( self, text: str, output_path: Union[str, Path], voice_type: str standard, speed: float 1.0, format: str mp3 ) - bool: 将文本合成为语音文件 Args: text: 要合成的文本 output_path: 输出文件路径 voice_type: 音色类型 speed: 语速0.5-2.0 format: 输出格式mp3/wav Returns: bool: 合成是否成功 try: # 确保输出目录存在 output_dir os.path.dirname(output_path) if output_dir: os.makedirs(output_dir, exist_okTrue) # 调用CosyVoice API # 这里根据实际SDK调整调用方式 audio_data self.client.synthesize( texttext, voicevoice_type, speedspeed, formatformat ) # 保存音频文件 with open(output_path, wb) as f: f.write(audio_data) print(f✓ 合成成功: {output_path}) return True except Exception as e: print(f✗ 合成失败: {str(e)}) return False这个类封装了基本的合成功能。我加了详细的参数说明和错误处理这样用起来更放心。2.2 批量处理功能很多时候我们需要一次处理多个文件比如把一本电子书分成多个章节转成音频。我们来添加批量处理功能from tqdm import tqdm from typing import List class BatchProcessor: 批量处理器 def __init__(self, synthesizer: CosyVoiceSynthesizer): self.synthesizer synthesizer def process_files( self, input_files: List[str], output_dir: str, voice_type: str standard, format: str mp3 ): 批量处理多个文本文件 Args: input_files: 输入文件列表 output_dir: 输出目录 voice_type: 音色类型 format: 输出格式 if not os.path.exists(output_dir): os.makedirs(output_dir) success_count 0 total_count len(input_files) print(f开始批量处理 {total_count} 个文件...) # 使用tqdm显示进度条 for input_file in tqdm(input_files, desc处理进度): try: # 读取文本内容 with open(input_file, r, encodingutf-8) as f: text f.read().strip() if not text: print(f警告: {input_file} 为空文件跳过) continue # 生成输出文件名 base_name os.path.splitext(os.path.basename(input_file))[0] output_file os.path.join(output_dir, f{base_name}.{format}) # 合成语音 if self.synthesizer.synthesize( texttext, output_pathoutput_file, voice_typevoice_type, formatformat ): success_count 1 except Exception as e: print(f处理文件 {input_file} 时出错: {str(e)}) print(f\n批量处理完成成功: {success_count}/{total_count})批量处理功能加上了进度条处理大量文件时能清楚看到进度不会让人干等着。3. 命令行接口设计核心功能写好了现在来设计命令行接口。我们用argparse库来解析命令行参数。3.1 基础参数解析打开cosyvoice_cli/cli.py先写参数解析部分import argparse import sys from pathlib import Path from typing import List def parse_arguments(): 解析命令行参数 parser argparse.ArgumentParser( descriptionCosyVoice命令行工具 - 快速语音合成, formatter_classargparse.RawDescriptionHelpFormatter, epilog 使用示例: # 从文本生成语音 cosyvoice-cli -t 你好世界 -o hello.mp3 # 从文件生成语音 cosyvoice-cli -f input.txt -o output.mp3 # 批量处理多个文件 cosyvoice-cli -b file1.txt file2.txt -d outputs/ # 指定音色和语速 cosyvoice-cli -t 测试文本 -o test.wav --voice female --speed 1.2 ) # 输入方式组互斥 input_group parser.add_mutually_exclusive_group(requiredTrue) input_group.add_argument( -t, --text, help直接输入要合成的文本 ) input_group.add_argument( -f, --file, help从文件读取文本 ) input_group.add_argument( -b, --batch, nargs, help批量处理多个文件 ) # 输出参数 parser.add_argument( -o, --output, requiredTrue, help输出文件路径单文件或目录批量 ) # 音频参数 parser.add_argument( --voice, defaultstandard, choices[standard, female, male, child], help音色类型默认: standard ) parser.add_argument( --speed, typefloat, default1.0, help语速0.5-2.0默认: 1.0 ) parser.add_argument( --format, defaultmp3, choices[mp3, wav, ogg], help输出格式默认: mp3 ) # 其他参数 parser.add_argument( --api-key, helpCosyVoice API密钥也可通过环境变量COSYVOICE_API_KEY设置 ) parser.add_argument( --verbose, actionstore_true, help显示详细日志 ) return parser.parse_args()我设计了三种输入方式直接输入文本、从文件读取、批量处理多个文件。这样能满足不同场景的需求。3.2 主函数实现参数解析写好了现在来实现主函数把各个部分连接起来def main(): 命令行工具主函数 # 解析参数 args parse_arguments() # 初始化合成器 from .core import CosyVoiceSynthesizer try: synthesizer CosyVoiceSynthesizer(api_keyargs.api_key) except ValueError as e: print(f初始化失败: {e}) print(请设置API密钥) print( 1. 通过 --api-key 参数) print( 2. 或设置环境变量 COSYVOICE_API_KEY) sys.exit(1) # 根据输入方式处理 if args.text: # 直接输入文本 handle_text_input(synthesizer, args) elif args.file: # 从文件读取 handle_file_input(synthesizer, args) elif args.batch: # 批量处理 handle_batch_input(synthesizer, args) print(任务完成) def handle_text_input(synthesizer, args): 处理直接文本输入 if args.verbose: print(f合成文本: {args.text[:50]}...) print(f输出文件: {args.output}) success synthesizer.synthesize( textargs.text, output_pathargs.output, voice_typeargs.voice, speedargs.speed, formatargs.format ) if not success: sys.exit(1) def handle_file_input(synthesizer, args): 处理文件输入 try: with open(args.file, r, encodingutf-8) as f: text f.read() if args.verbose: print(f从文件读取: {args.file}) print(f文本长度: {len(text)} 字符) success synthesizer.synthesize( texttext, output_pathargs.output, voice_typeargs.voice, speedargs.speed, formatargs.format ) if not success: sys.exit(1) except FileNotFoundError: print(f错误: 文件不存在 {args.file}) sys.exit(1) except Exception as e: print(f读取文件失败: {str(e)}) sys.exit(1) def handle_batch_input(synthesizer, args): 处理批量输入 from .core import BatchProcessor processor BatchProcessor(synthesizer) # 检查输出路径是否为目录 output_dir args.output if not os.path.isdir(output_dir): print(f错误: 批量处理时输出路径必须是目录) print(f请创建目录: mkdir -p {output_dir}) sys.exit(1) processor.process_files( input_filesargs.batch, output_diroutput_dir, voice_typeargs.voice, formatargs.format ) if __name__ __main__: main()主函数根据不同的输入方式调用对应的处理函数逻辑很清晰。错误处理也考虑得比较周全。4. 打包与安装配置工具写好了我们还要让它能像其他命令行工具一样方便安装和使用。4.1 编写setup.py创建setup.py文件这是Python包的安装配置文件from setuptools import setup, find_packages with open(README.md, r, encodingutf-8) as fh: long_description fh.read() setup( namecosyvoice-cli, version0.1.0, authorYour Name, author_emailyour.emailexample.com, description命令行工具 for CosyVoice语音合成, long_descriptionlong_description, long_description_content_typetext/markdown, urlhttps://github.com/yourusername/cosyvoice-cli, packagesfind_packages(), classifiers[ Programming Language :: Python :: 3, Programming Language :: Python :: 3.7, Programming Language :: Python :: 3.8, Programming Language :: Python :: 3.9, License :: OSI Approved :: MIT License, Operating System :: OS Independent, ], python_requires3.7, install_requires[ argparse1.4.0, tqdm4.65.0, # CosyVoice SDK根据实际情况添加 ], entry_points{ console_scripts: [ cosyvoice-clicosyvoice_cli.cli:main, ], }, )关键在entry_points部分它告诉Python安装后创建一个叫cosyvoice-cli的命令。4.2 安装和使用现在可以安装我们的工具了# 开发模式安装可编辑 pip install -e . # 或者普通安装 pip install .安装后就可以在命令行使用了# 查看帮助 cosyvoice-cli --help # 测试简单合成 cosyvoice-cli -t 这是一个测试 -o test.mp3 # 从文件合成 cosyvoice-cli -f novel_chapter1.txt -o chapter1.mp3 --voice female # 批量处理 cosyvoice-cli -b chapter*.txt -d audio_chapters/ --format wav4.3 编写使用说明一个好的工具要有清晰的文档。在README.md里写上使用说明# CosyVoice命令行工具 一个轻量级的命令行工具用于快速调用CosyVoice语音合成服务。 ## 功能特性 - 支持文本直接输入、文件读取、批量处理 - 多种音色选择标准、女声、男声、童声 - ⚡ 可调节语速0.5x-2.0x - 支持MP3、WAV、OGG格式输出 - 批量处理显示进度条 ## 快速开始 1. 安装 bash pip install cosyvoice-cli设置API密钥export COSYVOICE_API_KEYyour-api-key-here使用示例# 简单合成 cosyvoice-cli -t 你好世界 -o hello.mp3 # 从文件合成 cosyvoice-cli -f input.txt -o output.wav --voice female # 批量处理 cosyvoice-cli -b file1.txt file2.txt -d outputs/详细参数查看完整参数说明cosyvoice-cli --help集成到脚本可以在Shell脚本中调用#!/bin/bash for chapter in chapters/*.txt; do base$(basename $chapter .txt) cosyvoice-cli -f $chapter -o audio/${base}.mp3 done## 5. 实用技巧与进阶功能 基础功能已经完成了但要让工具更好用还需要一些实用技巧。 ### 5.1 添加配置文件支持 每次都输API密钥挺麻烦的我们可以添加配置文件支持 python # 在utils.py中添加 import json import os from pathlib import Path def get_config_dir(): 获取配置目录 home Path.home() config_dir home / .config / cosyvoice config_dir.mkdir(parentsTrue, exist_okTrue) return config_dir def load_config(): 加载配置文件 config_file get_config_dir() / config.json if config_file.exists(): with open(config_file, r) as f: return json.load(f) return {} def save_config(config): 保存配置文件 config_file get_config_dir() / config.json with open(config_file, w) as f: json.dump(config, f, indent2) def set_api_key(api_key): 设置API密钥到配置文件 config load_config() config[api_key] api_key save_config(config) print(API密钥已保存到配置文件)然后在命令行工具里添加配置命令# 在cli.py的parse_arguments中添加子命令 subparsers parser.add_subparsers(destcommand, help子命令) # 配置命令 config_parser subparsers.add_parser(config, help配置管理) config_parser.add_argument(--set-api-key, help设置API密钥) # 在main函数中处理子命令 if args.command config: if args.set_api_key: from .utils import set_api_key set_api_key(args.set_api_key) else: from .utils import load_config config load_config() print(当前配置:) for key, value in config.items(): print(f {key}: {value}) return这样用户就可以用cosyvoice-cli config --set-api-key your-key来保存密钥了。5.2 添加格式转换功能有时候我们需要在不同格式间转换可以添加这个功能# 在core.py中添加 import subprocess from pathlib import Path class AudioConverter: 音频格式转换器 staticmethod def convert_format(input_file: str, output_file: str, target_format: str): 转换音频格式需要安装ffmpeg Args: input_file: 输入文件 output_file: 输出文件 target_format: 目标格式 try: # 检查ffmpeg是否安装 subprocess.run([ffmpeg, -version], capture_outputTrue, checkTrue) except (subprocess.CalledProcessError, FileNotFoundError): print(错误: 需要安装ffmpeg才能进行格式转换) print(安装方法: https://ffmpeg.org/download.html) return False # 构建转换命令 cmd [ ffmpeg, -i, input_file, -y, # 覆盖输出文件 output_file ] try: subprocess.run(cmd, capture_outputTrue, checkTrue) print(f✓ 格式转换成功: {output_file}) return True except subprocess.CalledProcessError as e: print(f✗ 格式转换失败: {e.stderr.decode()}) return False5.3 错误处理优化好的错误提示能让用户更快解决问题。我们优化一下错误处理# 在core.py的synthesize方法中添加更详细的错误处理 def synthesize(self, text: str, output_path: str, **kwargs) - bool: 增强版的合成方法 # 参数验证 if not text or not text.strip(): print(错误: 文本内容不能为空) return False if len(text) 5000: # 假设API限制 print(警告: 文本过长建议分割成多段) # 可以在这里添加自动分割逻辑 # 检查输出路径 output_path Path(output_path) if output_path.exists(): print(f警告: 文件已存在 {output_path}) # 可以询问是否覆盖这里简单跳过 return False # 检查目录权限 output_dir output_path.parent if not os.access(output_dir, os.W_OK): print(f错误: 没有写入权限 {output_dir}) return False # 原来的合成逻辑...6. 常见问题与解决在实际使用中可能会遇到一些问题。这里整理了几个常见问题和解决方法。问题1API密钥错误错误: 认证失败请检查API密钥解决方法检查密钥是否正确cosyvoice-cli config查看当前配置重新设置cosyvoice-cli config --set-api-key 新密钥检查环境变量echo $COSYVOICE_API_KEY问题2文本过长CosyVoice可能有文本长度限制如果遇到错误可以分割文本# 在utils.py中添加文本分割函数 def split_long_text(text, max_length1000): 将长文本分割成多段 paragraphs text.split(\n) chunks [] current_chunk for para in paragraphs: if len(current_chunk) len(para) 1 max_length: current_chunk para \n else: if current_chunk: chunks.append(current_chunk.strip()) current_chunk para \n if current_chunk: chunks.append(current_chunk.strip()) return chunks问题3网络连接问题如果API调用超时或失败可以添加重试机制import time from functools import wraps def retry_on_failure(max_retries3, delay1): 失败重试装饰器 def decorator(func): wraps(func) def wrapper(*args, **kwargs): for attempt in range(max_retries): try: return func(*args, **kwargs) except Exception as e: if attempt max_retries - 1: raise print(f尝试 {attempt 1} 失败{delay}秒后重试...) time.sleep(delay) return None return wrapper return decorator # 使用装饰器 retry_on_failure(max_retries3, delay2) def synthesize_with_retry(self, text, output_path): # 原来的合成逻辑 pass问题4内存不足处理大量文件时可能内存不足可以优化文件处理方式def process_large_files(self, file_list, output_dir): 处理大文件的优化版本 for input_file in file_list: # 逐行读取大文件 with open(input_file, r, encodingutf-8) as f: chunk [] chunk_size 0 for line in f: chunk.append(line) chunk_size len(line) # 达到一定大小就处理 if chunk_size 1000: # 每1000字符处理一次 text .join(chunk) # 合成这一块 # ... chunk [] chunk_size 0 # 处理剩余部分 if chunk: text .join(chunk) # 合成 # ...7. 总结写这个CosyVoice命令行工具的过程其实也是学习Python工程化开发的好机会。从最开始的简单脚本到后来加入参数解析、错误处理、配置文件、批量处理等功能工具变得越来越实用。用下来感觉最大的好处是效率提升。以前要写一堆代码才能完成的工作现在一行命令就搞定了。批量处理功能特别实用处理几十个文件也不用一直盯着。如果你刚开始接触命令行工具开发建议先从简单的功能开始然后逐步添加需要的特性。不用追求一次完美先让工具跑起来再慢慢优化。遇到问题就查文档、看错误信息大部分问题都能找到解决方法。这个工具还有很多可以扩展的地方比如添加更多音频效果选项、支持流式合成、集成到其他工作流中等等。你可以根据自己的需求来定制。关键是要让工具真正解决实际问题而不是为了写工具而写工具。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
