nuclear 插件怎么用 yt-dlp API 搜索 YouTube 并解析音频流 URL【免费下载链接】nuclearStreaming music player that finds free music for you项目地址: https://gitcode.com/GitHub_Trending/nu/nuclearNuclear 的插件体系通过nuclearplayer/plugin-sdk提供api.Ytdlp接口插件可以用它调用 yt-dlp 命令行工具完成两件事按关键词搜索 YouTube 视频search()以及把视频 ID 解析成可直接播放的音频流 URLgetStream()。这篇文章给出一个最小可用插件的完整写法从插件目录结构、可用性检查、搜索、到拿到stream_url并说明结果数据结构和 URL 会过期这个关键限制。前提条件只有一个且很硬yt-dlp 是系统依赖如果用户机器上没有可用的 yt-dlpapi.Ytdlp.available就是false此时调用search()或getStream()会抛出Error(YtdlpAPI: No host configured)。所以任何用到这个 API 的插件都必须先检查available。文档也明确指出除非你的插件要和 YouTube 集成否则基本用不到这个 API。先搭建插件骨架插件就是磁盘上一个带package.json和入口文件的文件夹Nuclear 运行时加载它不需要额外的构建步骤——TS 由应用即时编译。按 getting-started.md 的说明创建一个目录例如~/nuclear-plugins/yt-plugin在其中初始化package.json{ name: yt-plugin, version: 0.1.0, description: Search YouTube via yt-dlp, author: Your Name, main: index.ts, nuclear: { displayName: YT Plugin, categories: [other] } }main指向入口文件如果省略加载器会依次尝试index.js、index.ts、index.tsx然后是dist/index.*。入口文件导出一个插件对象可用生命周期钩子有onLoad导入时执行、onEnable在应用里把插件打开时执行、onDisable、onUnload。yt-dlp 的调用放在onEnable里即可因为此时api已经注入import type { NuclearPluginAPI } from nuclearplayer/plugin-sdk; export default { async onEnable(api: NuclearPluginAPI) { // 见下文各节 }, };检查 yt-dlp 是否可用api.Ytdlp.available是一个 boolean getterNuclear 只有在检测到系统上存在可工作的 yt-dlp 二进制时才会配置 yt-dlp hostavailable返回true才说明后续调用是安全的。文档给出的防护写法async onEnable(api: NuclearPluginAPI) { if (!api.Ytdlp.available) { api.Logger.warn(yt-dlp is not installed, skipping YouTube features); return; } // Safe to call search() and getStream() here },注意区分两种不可用的表现available为false时你自己提前返回但如果绕过检查直接调用search()/getStream()SDK 的YtdlpAPI类见 ytdlp.ts会显式抛出YtdlpAPI: No host configured。用 search() 搜索 YouTubesearch(query, maxResults?)返回PromiseYtdlpSearchResult[]。文档中的示例调用const results await api.Ytdlp.search(Radiohead Paranoid Android, 5); for (const result of results) { api.Logger.info(${result.title} (${result.id})); if (result.duration) { api.Logger.info(Duration: ${result.duration}s); } }maxResults是可选参数用来限制返回条数。返回值YtdlpSearchResult的字段定义与 types/ytdlp.ts 中的类型一致字段类型含义idstringYouTube 视频 IDtitlestring视频标题durationnumber \| null时长秒未知时为nullthumbnailstring \| null缩略图 URL不可用时为nullchannelstring \| null上传频道名未知时为null注意duration、thumbnail、channel都可能为null遍历结果时要么判空如上面示例对duration的判断要么只依赖必有的id和title。用 getStream() 把视频 ID 解析成音频流 URLgetStream(videoId)接收一个视频 ID返回PromiseYtdlpStreamInfo。文档给出的完整主路径是先搜索取第一条再解析const results await api.Ytdlp.search(Radiohead Paranoid Android, 1); if (results.length 0) return; const stream await api.Ytdlp.getStream(results[0].id); api.Logger.info(Stream URL: ${stream.stream_url});返回值YtdlpStreamInfo的字段字段类型含义stream_urlstring可直接播放的音频流 URLdurationnumber \| null时长秒titlestring \| null视频标题containerstring \| null容器格式文档示例为webmcodecstring \| null音频编码文档示例为opusURL 只能即取即用不能存起来这是用这个 API 必须记住的限制文档明确说明 YouTube 的音频流 URL 是临时ephemeral的几小时后会过期。不要把它存下来留待以后使用每次需要播放某首曲目时都重新调getStream()拿一个新的 URL。安装插件并验证写好后按 getting-started.md 的加载流程验证打开 Nuclear → Preference → Plugins左侧边栏。点Add Plugin选择插件文件夹即包含package.json和index.ts的那个目录。打开插件开关onEnable即被触发。Nuclear 安装插件时会先读取package.json再把插件内容复制到 appdata 下的plugins/pluginName/pluginVersion目录并从那里加载已安装插件登记在plugins.json中启动时按安装日期顺序加载见 plugin-system.md。验证方式就是看日志输出onEnable里用api.Logger.info打出的Stream URL: ...一行出现且内容是一个 URL说明search()→getStream()链路走通。如果日志里出现你Logger.warn的 yt-dlp is not installed 信息说明当前环境available为false此时不应继续调用只能先在系统上装好 yt-dlp 再启用插件。相关实现位置SDK 侧 API 与错误行为YtdlpAPI 类availablegetter 判断 host 是否存在三个方法在无 host 时都抛YtdlpAPI: No host configured。TS 类型定义YtdlpSearchResult / YtdlpStreamInfo 等文件头部注释说明这些类型对应packages/player/src-tauri/src/ytdlp.rs中的 Rust 类型。官方 API 文档本文主要依据ytdlp.md。api.Ytdlp还有一个getPlaylist(url)方法返回YtdlpPlaylistInfo含按顺序排列的entries用于读取播放列表 URL 的条目它不在搜索 解析音频流这条主路径上需要时再参考 ytdlp.md 中的YtdlpPlaylistInfo/YtdlpPlaylistEntry类型表。限制yt-dlp 未安装时整个 API 不可用插件只能降级跳过 YouTube 功能无法在应用内补救。文档定位该 API 主要服务于 streaming provider 类插件大多数插件用不到它如果你的插件目标是别的场景先确认是否真的需要引入这个依赖。流 URL 有过期时间文档表述为 a few hours任何缓存 URL的设计都与文档要求相悖。【免费下载链接】nuclearStreaming music player that finds free music for you项目地址: https://gitcode.com/GitHub_Trending/nu/nuclear创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考