Description

Integrate with Emby Server API to manage media libraries, users, playback, live TV, devices, and encoding settings through comprehensive endpoints.

README (SKILL.md)

Emby Server API Skill

Name: emby
Author: xusanhong

Configuration

配置参数位于 emby.py 文件顶部:

BASE_URL = "https://emby.example.com/emby"  # 修改为你的Emby服务器地址
API_KEY = "652436b1ffa84d9a85f579eeb34b87aa"     # 修改为你的API Key

使用方式

导入 emby 模块并调用相应函数:

from emby import get_items, get_user_by_id, download_item_image

返回值类型

JSON返回: 大多数API调用返回 Dict (字典)
Stream返回: 图片、视频、音频下载等返回 Response 对象或 bytes

Stream 类型函数 (返回 Response)

函数	用途
`get_item_image()`	获取媒体项图片
`download_item_image()`	下载媒体项图片到文件或返回bytes
`get_video_stream_url()`	获取视频流地址
`download_video()`	下载视频到文件或返回bytes
`get_audio_stream_url()`	获取音频流地址
`download_audio()`	下载音频到文件或返回bytes
`post_devices_camera_uploads()`	上传摄像头内容
`restore_backup()`	恢复备份

常用函数示例

查询媒体库

# 查询所有电影
movies = get_items(include_item_types="Movie", recursive=True, limit=20)

# 搜索媒体
results = get_items(search_term="avatar", recursive=True)

# 按类型查询
series = get_items(include_item_types="Series", recursive=True)

用户管理

# 获取所有用户
users = query_users()

# 获取指定用户
user = get_user_by_id("user-id-here")

# 标记影片为已播放
mark_item_played(user_id="user-id", item_id="item-id")

图片操作

# 获取图片Response对象
resp = get_item_image(item_id="xxx", image_type="Primary", index=0)

# 下载图片到文件
download_item_image(item_id="xxx", image_type="Primary", output_path="poster.jpg")

# 直接获取图片bytes
bytes_data = download_item_image(item_id="xxx", image_type="Primary")

视频/音频下载

# 下载视频
download_video(item_id="xxx", output_path="movie.mp4")

# 下载音频
download_audio(item_id="xxx", output_path="song.mp3")

Live TV

# 获取频道
channels = get_live_tv_channels()

# 获取节目指南
programs = get_live_tv_programs(channel_id="xxx", start_time="2024-01-01", end_time="2024-01-07")

# 获取录制
recordings = get_live_tv_recordings()

完整API列表

详见 emby.py 文件，包含以下分类:

Artists - 艺术家相关
Albums - 专辑相关
Codecs - 编解码器
Channels/Collections - 频道/收藏
Devices - 设备管理
Genres - 类型
Items - 媒体项
Users - 用户管理
UserData - 用户数据
Sessions - 会话
Playlists - 播放列表
Plugins - 插件
Library - 媒体库
LiveTV - 直播电视
LiveStreams - 直播流
Localization - 本地化
Movies - 电影
AudioBooks - 有声书
Auth - 认证
Backup - 备份
Branding - 品牌
Connect - Emby Connect
DisplayPreferences - 显示偏好
DLNA - DLNA
Encoding - 编码设置
Environment - 环境
Images - 图片
Packages - 包
Persons - 人物
Studios - 工作室
Tags - 标签
Trailers - 预告片
Years - 年份
Features - 特性
UI - 用户界面
Videos - 视频操作
Web - Web配置
OpenAPI - OpenAPI文档
Playback - 播放
Hubs - 中心
Search - 搜索

Usage Guidance

This skill is a plausible Emby API client, but do not install or use it as-is without changes: (1) The distributed emby.py contains a hard-coded API_KEY — treat that as a leaked test key and do not reuse it. Replace it by reading credentials from environment variables (e.g., EMBY_BASE_URL and EMBY_API_KEY) and update SKILL.md to declare those requirements. (2) Review functions that download, upload, or restore backups (they can move or overwrite data) and limit the API key’s permissions accordingly. (3) Run the code in an isolated environment and inspect network activity to confirm it only talks to your Emby server. (4) Prefer the maintainer provide a version that reads configuration from env vars or a secure config store rather than instructing users to edit source files. If you need higher assurance, ask the publisher to explain why a key is hard-coded and request a version that follows secure credential handling.

Capability Analysis

Type: OpenClaw Skill Name: emby Version: 1.0.0 The skill provides a comprehensive wrapper for the Emby Media Server API but includes high-risk file I/O capabilities in emby.py. Specifically, functions like 'post_devices_camera_uploads' allow reading arbitrary local files for upload, and 'download_video'/'download_audio' allow writing to arbitrary local paths without any sanitization or directory anchoring. While these features align with the stated media management purpose, they function as primitives for data exfiltration or system file overwriting if the agent is targeted by prompt injection. No explicit malicious intent, obfuscation, or hardcoded malicious endpoints were identified.

Capability Assessment

✓ Purpose & Capability

Name/description match the provided code: emby.py implements a large wrapper around Emby Server endpoints (items, users, playback, LiveTV, images, backups, etc.). The requested capabilities align with what an Emby integration would need (HTTP requests to an Emby server). There are no unrelated service credentials, binaries, or config paths requested.

⚠ Instruction Scope

SKILL.md instructs users to edit BASE_URL and API_KEY at the top of emby.py to point to their server and API key. That instruction is within the task's scope (configuring the client) but grants broad discretion to modify source code and embed secrets. The documentation also references operations that can upload/restore backups and upload camera content — these are powerful operations that should be clearly documented and permissioned, but they are expected for a full-featured Emby client. SKILL.md does not instruct reading unrelated files or environment values, nor does it instruct exfiltration to unexpected endpoints.

✓ Install Mechanism

No install spec — instruction-only plus an included Python module. That is low-risk compared to arbitrary downloads or install scripts. The code depends on requests (standard for HTTP) but no package install is declared in the registry metadata; user will need to ensure 'requests' is available.

⚠ Credentials

The skill declares no required environment variables or primary credential, yet the distributed code contains a literal API_KEY value and instructs editing emby.py to insert credentials. Embedding a secret in the codebase (or asking users to put secrets in source) is poor practice and increases risk of accidental leakage or misuse. The skill should instead declare a required env var (e.g., EMBY_API_KEY and EMBY_BASE_URL) and read them at runtime. Additionally, functions that download/upload media and restore backups are capable of moving data; verify the API key's scope and rotate it if it was used for testing.

✓ Persistence & Privilege

always is false and the skill is user-invocable; it does not request persistent system-wide privileges or modify other skills. Autonomous invocation is allowed by platform default but is not combined with other privilege escalation indicators here.

Version History

v1.0.0

Initial release of Emby Server API skill. - Provides comprehensive integration with Emby media server for library, user, device, playback, and live TV management. - Supports querying and managing movies, series, artists, albums, genres, and more. - Enables user authentication, playback control, and marking titles as played. - Includes functions for media downloads, image handling, and device operations. - Offers live TV channel and recording management. - Configuration via BASE_URL and API_KEY at the top of the module.

Metadata

Slug emby

Version 1.0.0

License MIT-0

All-time Installs 1

Active Installs 1

Total Versions 1

Frequently Asked Questions

What is emby?

Integrate with Emby Server API to manage media libraries, users, playback, live TV, devices, and encoding settings through comprehensive endpoints. It is an AI Agent Skill for Claude Code / OpenClaw, with 356 downloads so far.

How do I install emby?

Run "/install emby" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is emby free?

Yes, emby is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does emby support?

emby is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created emby?

It is built and maintained by XuSanHong (@xusanhong); the current version is v1.0.0.

More Skills

emby