媒体服务器控制（免费版）

概述

媒体服务器控制免费版是一款面向个人用户的 Jellyfin 媒体服务器控制工具。通过命令行一键控制 Jellyfin 播放，支持内容搜索、智能续播、设备发现与播放控制。无需复杂的 GUI 操作，适合家庭影音娱乐场景的快速控制需求。

核心能力

已知限制

执行已知限制操作,使用input_params参数进行配置,支持创建/查询/导出等操作。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

仅支持控制单台电视设备

仅支持控制单台电视设备

输入: 用户提供仅支持控制单台电视设备所需的指令和必要参数。 处理: 按照skill规范执行仅支持控制单台电视设备操作,遵循单一意图原则。 输出: 返回仅支持控制单台电视设备的执行结果,包含操作状态和输出数据。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

不支持多用户配置管理

不支持多用户配置管理

输入: 用户提供不支持多用户配置管理所需的指令和必要参数。 处理: 按照skill规范执行不支持多用户配置管理操作,遵循单一意图原则。 输出: 返回不支持多用户配置管理的执行结果,包含操作状态和输出数据。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

不支持定时播放功能

不支持定时播放功能

输入: 用户提供不支持定时播放功能所需的指令和必要参数。 处理: 按照skill规范执行不支持定时播放功能操作,遵循单一意图原则。 输出: 返回不支持定时播放功能的执行结果,包含操作状态和输出数据。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

不支持媒体库自动扫描

不支持媒体库自动扫描

输入: 用户提供不支持媒体库自动扫描所需的指令和必要参数。 处理: 按照skill规范执行不支持媒体库自动扫描操作,遵循单一意图原则。 输出: 返回不支持媒体库自动扫描的执行结果,包含操作状态和输出数据。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

不支持播放历史统计

不支持播放历史统计

输入: 用户提供不支持播放历史统计所需的指令和必要参数。 处理: 按照skill规范执行不支持播放历史统计操作,遵循单一意图原则。 输出: 返回不支持播放历史统计的执行结果,包含操作状态和输出数据。

• 执行此能力时使用input_params参数,支持创建/查询/导出操作

输入: 用户提供已知限制所需的指令和必要参数。 处理: 按照skill规范执行已知限制操作,遵循单一意图原则。 输出: 返回已知限制的执行结果,包含操作状态和输出数据。 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：轻量级、Jellyfin、媒体服务器控制工、支持内容搜索、播放控制与设备管、适合个人家庭影音、娱乐使用、核心能力、搜索内容并自动开、始播放、自动定位上次观看、自动检测可控设备、下一集、音量控制等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

场景一：一键播放电视剧

用户想继续观看某部电视剧的下一集。

# 一键播放（自动开机、启动应用、找到下一集、播放）
node skills/jellyfin-control/cli.js tv play "Breaking Bad"

系统自动完成：搜索内容 → 找到下一集 → 开启电视 → 启动 Jellyfin 应用 → 开始播放。

场景二：播放电影

用户想观看某部电影。

# 播放电影
node skills/jellyfin-control/cli.js tv play "The Matrix"

场景三：续播控制

电视已开启，Jellyfin 已运行，直接续播。

# 续播
node skills/jellyfin-control/cli.js resume "Breaking Bad"

# 指定设备续播
node skills/jellyfin-control/cli.js resume "Matrix" --device "Chromecast"

不适用场景

以下场景媒体服务器控制不适合处理：

• 实时流数据处理
• 小规模数据手动分析
• 非结构化文本情感分析

触发条件

需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求。

快速开始

1. 阅读## 核心能力章节了解skill功能
2. 按## 依赖说明配置环境
3. 执行所需能力对应的命令
4. 参考## 错误处理章节处理异常
5. 查看## FAQ解答常见疑问

基础配置（仅 Jellyfin，无电视控制）

{
  "skills": {
    "entries": {
      "jellyfin-control": {
        "env": {
          "JF_URL": "http://YOUR_IP:8096",
          "JF_API_KEY": "your-api-key-here",
          "JF_USER": "your-username"
        }
      }
    }
  }
}

配置电视控制（Home Assistant）

{
  "skills": {
    "entries": {
      "jellyfin-control": {
        "env": {
          "JF_URL": "http://192.168.1.50:8096",
          "JF_API_KEY": "your-jellyfin-api-key",
          "JF_USER": "username",
          "HA_URL": "http://192.168.1.138:8123",
          "HA_TOKEN": "your-ha-long-lived-token",
          "HA_TV_ENTITY": "media_player.lg_webos_tv",
          "TV_MAC": "AA:BB:CC:DD:EE:FF"
        }
      }
    }
  }
}

验证配置

# 搜索内容验证
node skills/jellyfin-control/cli.js search "Star Wars"

# 查看媒体库统计
node skills/jellyfin-control/cli.js stats

结果处理: 执行完成后,查看输出结果确认操作状态。成功时输出包含处理摘要和结果数据;失败时根据错误信息排查问题,查阅错误处理章节获取恢复步骤。

命令参数说明

• -on-LAN: 命令参数,用于指定操作选项
• -Emby-Token: 命令参数,用于指定操作选项
• -H: 命令参数,用于指定操作选项

示例

环境变量说明

Jellyfin 配置（必需）

电视控制配置（可选）

电视后端选择

最佳实践

一键播放流程

用户执行 cli.js tv play "内容名称"
    │
    ├── 1. 搜索 Jellyfin 内容（快速失败）
    ├── 2. 找到下一未观看集
    ├── 3. Wake-on-LAN 唤醒电视
    ├── 4. 等待 10 秒启动
    ├── 5. 启动 Jellyfin 应用
    ├── 6. 等待 8 秒会话注册
    ├── 7. 查找 Jellyfin 会话（重试 3 次）
    └── 8. 在会话上播放内容

常用控制命令

# 电视控制
node skills/jellyfin-control/cli.js tv on           # 开启电视
node skills/jellyfin-control/cli.js tv off          # 关闭电视
node skills/jellyfin-control/cli.js tv launch       # 启动 Jellyfin 应用

# 播放控制
node skills/jellyfin-control/cli.js control pause    # 暂停
node skills/jellyfin-control/cli.js control play     # 播放
node skills/jellyfin-control/cli.js control next     # 下一集
node skills/jellyfin-control/cli.js control vol 50   # 音量 50%

# 内容搜索
node skills/jellyfin-control/cli.js search "Star Wars"

后端选择建议

常见问题

无法连接 Jellyfin 服务器

# 检查服务器状态
curl http://YOUR_IP:8096/health

# 验证 API Key
curl -H "X-Emby-Token: YOUR_API_KEY" http://YOUR_IP:8096/System/Info

# 检查网络连通性
ping YOUR_IP

电视无法开启

# 检查 MAC 地址配置
echo $TV_MAC

# 验证 Wake-on-LAN
node skills/jellyfin-control/cli.js tv on --debug

# 手动开启电视后重试

播放内容找不到

# 搜索内容确认存在
node skills/jellyfin-control/cli.js search "内容名称"

# 尝试模糊搜索
node skills/jellyfin-control/cli.js search "Matrix"

# 查看媒体库统计
node skills/jellyfin-control/cli.js stats

Home Assistant 连接失败

# 检查 HA 服务状态
curl http://HA_URL/api/

# 验证令牌
curl -H "Authorization: Bearer YOUR_TOKEN" http://HA_URL/api/states

依赖说明

运行环境

• Agent 平台：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
• 操作系统：Windows / macOS / Linux
• Node.js：14.0 及以上
• 网络环境：需可访问 Jellyfin 服务器和电视设备

依赖详情

API Key 配置

# Jellyfin API Key
# 获取方式：Jellyfin 控制台 → 高级 → API 密钥
JF_API_KEY=your_jellyfin_api_key

# Home Assistant 令牌（如使用 HA）
# 获取方式：HA → 个人资料 → 长期访问令牌
HA_TOKEN=your_ha_long_lived_token

可用性分类

• 分类：MD+EXEC（纯 Markdown 指令，部分功能需要 exec 命令行执行能力）
• 说明：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 执行任务
• 适用人群：个人家庭用户、影音爱好者
• 升级建议：如需多设备管理、多用户、定时播放等高级功能，请使用 PRO 版本
• API Key通过环境变量配置: export API_KEY=your_key

错误处理