Headphones项目API接口详解与技术指南

Headphones项目API接口详解与技术指南

headphones Automatic music downloader for SABnzbd 项目地址: https://gitcode.com/gh_mirrors/he/headphones

概述

Headphones项目提供了一套完整的API接口，用于管理和控制音乐收藏系统。这套API允许开发者通过HTTP请求与系统交互，实现艺术家管理、专辑查询、下载控制等功能。本文将全面解析这些API的使用方法和应用场景。

API基础结构

API采用标准的HTTP请求方式，请求地址格式为： http://ip:port + HTTP_ROOT + /api?apikey=$apikey&cmd=$command

所有响应数据均以JSON格式返回。对于执行类命令（如"delArtist"或"addArtist"），系统会返回"OK"状态；对于查询类命令，则返回请求的数据内容。

核心API功能解析

数据查询类API

1. 获取索引数据 (getIndex)

   • 功能：获取首页展示的所有艺术家信息
   • 返回字段包括：艺术家名称、排序名称、ID、状态、添加日期、最新专辑信息、曲目统计等
   • 特别说明：ArtworkURL和ThumbURL字段提供远程图片地址，如需获取本地缓存路径，需使用getArtistArt命令

2. 艺术家详情查询 (getArtist)

   • 功能：获取指定艺术家的详细信息
   • 参数：artistid - 艺术家唯一标识
   • 返回数据包含艺术家基本信息和专辑列表，专辑信息包括状态、ASIN编号、添加日期等

3. 专辑详情查询 (getAlbum)

   • 功能：获取指定专辑的完整信息
   • 返回数据结构分为三部分：专辑基本信息、描述信息和曲目列表
   • 曲目信息包含格式、时长、比特率等专业音频参数

4. 相似艺术家查询 (getSimilar)

   • 功能：基于当前艺术家查找相似艺术家
   • 返回结果按相似度排序，"Count"值越高表示相似度越高

管理控制类API

1. 艺术家管理

   • 添加艺术家 (addArtist)：将新艺术家加入数据库
   • 删除艺术家 (delArtist)：从数据库中移除艺术家
   • 暂停/恢复艺术家 (pauseArtist/resumeArtist)：控制艺术家的监控状态
   • 刷新艺术家信息 (refreshArtist)：从MusicBrainz更新艺术家数据

2. 专辑管理

   • 添加专辑 (addAlbum)：通过发行ID添加新专辑
   • 队列管理 (queueAlbum/unqueueAlbum)：控制专辑的下载状态
   • 参数说明：queueAlbum支持new和lossless参数，分别控制是否寻找新版本和仅无损格式

3. 系统操作

   • 强制搜索 (forceSearch)：立即执行专辑搜索任务
   • 强制处理 (forceProcess)：手动触发下载目录的后处理
   • 艺术家更新 (forceActiveArtistsUpdate)：强制更新活跃艺术家信息

高级功能API

1. 精确下载控制

   • 选择特定下载 (choose_specific_download)：返回专辑搜索结果的原始数据
   • 下载指定发布 (download_specific_release)：配合上条命令，实现精确下载控制
   • 技术要点：需要完整传递title、size、url等参数才能成功触发下载

2. 图片资源获取

   • 获取艺术家/专辑图片 (getArtistArt/getAlbumArt)：返回本地缓存路径或远程URL
   • 获取缩略图 (getArtistThumb/getAlbumThumb)：专为缩略图优化的接口

3. 信息获取

   • 艺术家/专辑信息 (getArtistInfo/getAlbumInfo)：返回HTML格式的详细描述
   • 版本信息 (getVersion)：获取系统版本和更新状态

最佳实践建议

1. 错误处理：目前API尚未实现完善的错误代码机制，建议开发者自行添加请求超时和异常处理逻辑。

2. 图片缓存策略：对于ArtworkURL和ThumbURL，建议优先使用getArtistArt/getAlbumArt获取本地缓存路径，减少网络请求。

3. 批量操作优化：对于大量艺术家或专辑操作，建议合理控制请求频率，避免系统过载。

4. 版本控制：在执行update命令前，务必通过getVersion检查安装类型，避免不兼容的更新操作。

技术注意事项

1. 部分API如getLogs尚未实现功能，使用时需注意兼容性。

2. 强制类操作（forceSearch等）会阻塞当前线程，在Web应用中应谨慎使用。

3. 相似艺术家算法基于统计数据进行推荐，"Count"值可作为相似度参考指标。

4. 音频文件元数据中的CleanName字段已去除标点和特殊格式，适合用于标准化处理。

这套API为Headphones项目提供了完整的程序化控制能力，开发者可以根据需求灵活组合各种接口，构建个性化的音乐收藏管理系统。随着项目发展，API功能将持续完善，建议保持关注后续更新。

headphones Automatic music downloader for SABnzbd 项目地址: https://gitcode.com/gh_mirrors/he/headphones