Homepage 集成 TautulliPlexWidget实时监控播放流的完整配置指南【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage本文以 Homepage 开源项目中的 Tautulli 服务 Widget 文档 为主体介绍如何在 Homepage 中接入 TautulliPlex 媒体服务器监控工具在个人主页/应用仪表板上实时展示当前活跃的 Plex 播放流。读完本文你将掌握 API Key 获取、YAML 配置的每个参数含义与默认值并能结合源码理解该 Widget 的底层请求链路、渲染逻辑与排错方法。一、功能概述为什么在 Homepage 中集成 TautulliTautulli原名 PlexPy是 Plex 生态中流行的第三方监控与统计工具能够记录播放历史、追踪活跃会话、统计带宽与转码情况。Homepage 的 Tautulli Widget 定位十分聚焦实时展示当前正在进行的 Plex 播放流active streams包括正在播放的媒体标题、观看进度、播放/暂停状态、视频与音频的决策Direct Play / Copy / Transcode等信息让你在打开个人主页时即可一眼掌握媒体服务器的实时负载。从官方文档的定位描述看docs/widgets/services/plex-tautulli.mdProvides detailed information about currently active streams.即该 Widget 只围绕当前活跃播放流这一核心场景不承担历史统计等 Tautulli 的其他能力配置上也因此非常简单——没有可配置的显示字段Allowed fields: no configurable fields for this widget只通过少量布尔选项调整展示细节。二、前置条件获取 Tautulli API KeyHomepage 通过 Tautulli 的 HTTP API 拉取实时数据因此需要 API Key 才能访问。获取方式如下登录 Tautulli 的 Web 界面进入Settings Web Interface API在该页面中复制 API Key一串较长的字符串。该 Key 将作为配置项key填入 Homepage 的 Widget 配置中。值得注意的是Tautulli 的 API 默认要求请求携带apikey参数详见下文源码分析Homepage 正是以该参数形式透传认证信息的。三、Widget 配置指南3.1 最小可运行配置在 Homepage 的services.yaml或对应的分组配置中新增一个服务条目将widget.type设为tautulli并填入 Tautulli 服务的 URL 与 API Key- Tautulli: icon: tautulli.png href: http://tautulli.host.or.ip:port description: Plex 监控 widget: type: tautulli url: http://tautulli.host.or.ip:port key: apikeyapikeyapikeyapikeyapikeyurlTautulli 服务地址格式为http://tautulli.host.or.ip:port需与 Tautulli 实际监听端口默认 8181一致key上一节获取的 API Key。3.2 完整参数与默认值根据 docs/widgets/services/plex-tautulli.md 中的官方示例该 Widget 的全部可用参数如下widget: type: tautulli url: http://tautulli.host.or.ip:port key: apikeyapikeyapikeyapikeyapikey enableUser: true # optional, defaults to false showEpisodeNumber: true # optional, defaults to false expandOneStreamToTwoRows: false # optional, defaults to true参数说明参数类型默认值作用typestring必填固定为tautulli用于加载对应 Widget 实现urlstring必填Tautulli 服务地址含端口keystring必填Tautulli API KeyenableUserbooleanfalse是否在流标题后显示播放用户friendly_nameshowEpisodeNumberbooleanfalse对剧集类媒体是否显示 Sxx · Exx 集数信息expandOneStreamToTwoRowsbooleantrue当只有一个活跃播放流时是否展开为两行显示标题行 进度行这三个布尔参数的默认值均有对应源码实现支撑详见下文第四、五节。四、源码级原理请求如何从 Widget 到达 Tautulli4.1 API 模板与 Endpoint 映射Tautulli Widget 的核心定义位于 src/widgets/tautulli/widget.js代码非常精简import genericProxyHandler from utils/proxy/handlers/generic; const widget { api: {url}/api/v2?apikey{key}cmd{endpoint}, proxyHandler: genericProxyHandler, mappings: { get_activity: { endpoint: get_activity, }, }, }; export default widget;可以提炼出几个关键事实Widget 通过 Tautulli 的API v2接口获取数据最终请求 URL 形如{url}/api/v2?apikey{key}cmdget_activitycmdget_activity是 Tautulli API 中用于查询当前活跃会话的命令与本文档active streams的定位完全对应该 Widget 使用通用的genericProxyHandler作为代理处理器没有自定义的响应映射mappings仅声明 endpoint。4.2 通用代理链路服务端如何透传请求Homepage 的所有 Widget 请求都先打到项目自身的 API 路由再由服务端代理转发到目标服务避免在浏览器端暴露 API Key。Tautulli Widget 走的是通用链路核心实现在 src/utils/proxy/handlers/generic.js从请求 query 中解析group、service、endpoint、index通过getServiceWidget读取当前服务的 Widget 配置使用formatApiCall(widgets[widget.type].api, { endpoint, ...widget })将{url}、{key}、{endpoint}等占位符替换为实际值拼出最终 URL通过httpProxy发起 HTTP 请求并做响应校验validateWidgetData与错误信息脱敏sanitizeErrorURL。前端侧组件通过 src/utils/proxy/use-widget-api.js 中封装的useSWR拉取数据并为get_activity设置了5000ms5 秒的刷新间隔见 src/widgets/tautulli/component.jsxconst { data: activityData, error: activityError } useWidgetAPI(widget, get_activity, { refreshInterval: 5000, });也就是说只要页面处于打开状态Tautulli Widget 每 5 秒会自动重新请求一次活跃会话数据保证仪表板上的播放状态接近实时。五、渲染行为详解三种展示形态与判断逻辑Tautulli Widget 的渲染组件在 src/widgets/tautulli/component.jsx 中实现其展示逻辑可以根据活跃流数量分为三种形态。5.1 加载态与空态加载中数据尚未返回时渲染 12 行占位符-无活跃流sessions为空数组时显示国际化文案tautulli.no_active英文为 No Active Streams简体中文为暂无播放见 public/locales/en/common.json 与 public/locales/zh-Hans/common.json连接错误请求失败或返回空数据时显示tautulli.plex_connection_error英文 Check Plex Connection简体中文检查Plex连接提示检查 Plex/Tautulli 连通性。5.2 单流双行展开expandOneStreamToTwoRows当expandOneStreamToTwoRows为true默认值且当前恰好只有一个活跃播放流时Widget 使用SingleSessionEntry渲染两行第一行标题行展示流标题并在右侧显示播放决策图标第二行进度行带进度的进度条背景左侧显示播放/暂停图标右侧显示当前观看位置 / 总时长格式为HH:MM:SS或MM:SS。多流时2 个及以上则退化为紧凑的单行模式SessionEntry每行显示状态图标、标题、播放决策图标和当前观看位置不再展示完整进度条与总时长。这个开关的默认值在源码中是这样生效的const expandOneStreamToTwoRows service.widget?.expandOneStreamToTwoRows ! false; // default is true即只有当显式配置为false时才会关闭双行展开不配置即为true。5.3 标题与集数显示enableUser / showEpisodeNumber标题的生成逻辑由generateStreamTitle完成function generateStreamTitle(session, enableUser, showEpisodeNumber) { let stream_title ; const { media_type, parent_media_index, media_index, title, grandparent_title, full_title, friendly_name } session; if (media_type episode showEpisodeNumber) { const season_str S${parent_media_index.toString().padStart(2, 0)}; const episode_str E${media_index.toString().padStart(2, 0)}; stream_title ${grandparent_title}: ${season_str} · ${episode_str} - ${title}; } else { stream_title full_title; } return enableUser ? ${stream_title} (${friendly_name}) : stream_title; }showEpisodeNumber: true当媒体类型为剧集episode时标题显示为剧名: S01 · E05 - 单集标题的格式方便快速定位季/集enableUser: true在标题末尾追加(用户名)其中用户名取自 Tautulli 会话中的friendly_name字段便于在多用户家庭环境中区分谁在观看。5.4 播放决策图标Direct Play / Copy / Transcode每行右侧的图标用于表达 Tautulli 返回的video_decision与audio_decision组合视频/音频决策图标含义均为direct playMdSmartDisplay实心显示器直接播放无任何转码均为copyMdOutlineSmartDisplay描边显示器容器/流复制remux接近无损其他组合BsFillCpuFill/BsCpu涉及转码CPU 参与处理图标语义结合国际化文案tautulli.playing播放中、tautulli.transcoding转码、tautulli.bitrate比特率使用可直观判断当前播放流的资源占用情况。5.5 排序规则获取到会话列表后组件会对sessions按view_offset当前观看位置毫秒进行升序排序后再渲染即观看进度靠前的播放流显示在上面const playing activityData.response.data.sessions.sort((a, b) { if (a.view_offset b.view_offset) return 1; if (a.view_offset b.view_offset) return -1; return 0; });六、测试与验证Widget 行为的自动化保障仓库为 Tautulli Widget 提供了完整的测试可作为理解其行为与验证配置合法性的参考src/widgets/tautulli/widget.test.js通过expectWidgetConfigShape校验 Widget 配置对象api、proxyHandler、mappings等符合项目约定的结构任何字段缺失都会导致测试失败src/widgets/tautulli/component.test.jsx使用vi.mock模拟useWidgetAPI覆盖三类关键场景加载中显示占位行-无活跃会话时显示tautulli.no_active文案单个会话播放时渲染双行展开且时间格式正确如view_offset: 1000毫秒渲染为00:01duration: 2000渲染为00:02。这些测试一方面验证了渲染逻辑的正确性另一方面也侧面印证了本文第五节描述的展示规则。七、常见问题与排错1. Widget 显示检查Plex连接Check Plex Connection该错误对应tautulli.plex_connection_error出现时说明请求 Tautulli 失败或返回数据为空。请依次检查url是否可从运行 Homepage 的主机访问注意不要写成 Plex 的地址而是 Tautulli 的地址key是否复制完整API Key 在Settings Web Interface API中查看Tautulli 服务是否运行正常、端口是否正确。2. 显示暂无播放No Active Streams但 Plex 明明在播放确认 Plex 用户确实在当前活跃播放而非暂停很久或已退出Tautulli 的get_activity接口只返回当前处于活动状态的会话。另外注意 Widget 每 5 秒刷新一次数据可能存在数秒延迟。3. 不想看到用户名 / 不想显示集数分别将enableUser、showEpisodeNumber配置为false或不配置因为默认即false。4. 希望单流时也保持一行将expandOneStreamToTwoRows显式设置为false此时无论活跃流数量多少都使用紧凑单行渲染。八、小结Homepage 的 Tautulli Widget 以实时活跃播放流监控为单一职责配置只需urlkey两个必填项配合enableUser、showEpisodeNumber、expandOneStreamToTwoRows三个可选开关即可适配不同展示偏好。底层通过服务端通用代理调用 Tautulli API v2 的get_activity命令前端每 5 秒刷新并针对 Direct Play / Copy / Transcode 提供直观的图标反馈。若需深入理解实现细节可继续阅读 src/widgets/tautulli/widget.js、src/widgets/tautulli/component.jsx 以及对应的 组件测试。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Homepage 集成 Tautulli（Plex）Widget：实时监控播放流的完整配置指南
Homepage 集成 TautulliPlexWidget实时监控播放流的完整配置指南【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage本文以 Homepage 开源项目中的 Tautulli 服务 Widget 文档 为主体介绍如何在 Homepage 中接入 TautulliPlex 媒体服务器监控工具在个人主页/应用仪表板上实时展示当前活跃的 Plex 播放流。读完本文你将掌握 API Key 获取、YAML 配置的每个参数含义与默认值并能结合源码理解该 Widget 的底层请求链路、渲染逻辑与排错方法。一、功能概述为什么在 Homepage 中集成 TautulliTautulli原名 PlexPy是 Plex 生态中流行的第三方监控与统计工具能够记录播放历史、追踪活跃会话、统计带宽与转码情况。Homepage 的 Tautulli Widget 定位十分聚焦实时展示当前正在进行的 Plex 播放流active streams包括正在播放的媒体标题、观看进度、播放/暂停状态、视频与音频的决策Direct Play / Copy / Transcode等信息让你在打开个人主页时即可一眼掌握媒体服务器的实时负载。从官方文档的定位描述看docs/widgets/services/plex-tautulli.mdProvides detailed information about currently active streams.即该 Widget 只围绕当前活跃播放流这一核心场景不承担历史统计等 Tautulli 的其他能力配置上也因此非常简单——没有可配置的显示字段Allowed fields: no configurable fields for this widget只通过少量布尔选项调整展示细节。二、前置条件获取 Tautulli API KeyHomepage 通过 Tautulli 的 HTTP API 拉取实时数据因此需要 API Key 才能访问。获取方式如下登录 Tautulli 的 Web 界面进入Settings Web Interface API在该页面中复制 API Key一串较长的字符串。该 Key 将作为配置项key填入 Homepage 的 Widget 配置中。值得注意的是Tautulli 的 API 默认要求请求携带apikey参数详见下文源码分析Homepage 正是以该参数形式透传认证信息的。三、Widget 配置指南3.1 最小可运行配置在 Homepage 的services.yaml或对应的分组配置中新增一个服务条目将widget.type设为tautulli并填入 Tautulli 服务的 URL 与 API Key- Tautulli: icon: tautulli.png href: http://tautulli.host.or.ip:port description: Plex 监控 widget: type: tautulli url: http://tautulli.host.or.ip:port key: apikeyapikeyapikeyapikeyapikeyurlTautulli 服务地址格式为http://tautulli.host.or.ip:port需与 Tautulli 实际监听端口默认 8181一致key上一节获取的 API Key。3.2 完整参数与默认值根据 docs/widgets/services/plex-tautulli.md 中的官方示例该 Widget 的全部可用参数如下widget: type: tautulli url: http://tautulli.host.or.ip:port key: apikeyapikeyapikeyapikeyapikey enableUser: true # optional, defaults to false showEpisodeNumber: true # optional, defaults to false expandOneStreamToTwoRows: false # optional, defaults to true参数说明参数类型默认值作用typestring必填固定为tautulli用于加载对应 Widget 实现urlstring必填Tautulli 服务地址含端口keystring必填Tautulli API KeyenableUserbooleanfalse是否在流标题后显示播放用户friendly_nameshowEpisodeNumberbooleanfalse对剧集类媒体是否显示 Sxx · Exx 集数信息expandOneStreamToTwoRowsbooleantrue当只有一个活跃播放流时是否展开为两行显示标题行 进度行这三个布尔参数的默认值均有对应源码实现支撑详见下文第四、五节。四、源码级原理请求如何从 Widget 到达 Tautulli4.1 API 模板与 Endpoint 映射Tautulli Widget 的核心定义位于 src/widgets/tautulli/widget.js代码非常精简import genericProxyHandler from utils/proxy/handlers/generic; const widget { api: {url}/api/v2?apikey{key}cmd{endpoint}, proxyHandler: genericProxyHandler, mappings: { get_activity: { endpoint: get_activity, }, }, }; export default widget;可以提炼出几个关键事实Widget 通过 Tautulli 的API v2接口获取数据最终请求 URL 形如{url}/api/v2?apikey{key}cmdget_activitycmdget_activity是 Tautulli API 中用于查询当前活跃会话的命令与本文档active streams的定位完全对应该 Widget 使用通用的genericProxyHandler作为代理处理器没有自定义的响应映射mappings仅声明 endpoint。4.2 通用代理链路服务端如何透传请求Homepage 的所有 Widget 请求都先打到项目自身的 API 路由再由服务端代理转发到目标服务避免在浏览器端暴露 API Key。Tautulli Widget 走的是通用链路核心实现在 src/utils/proxy/handlers/generic.js从请求 query 中解析group、service、endpoint、index通过getServiceWidget读取当前服务的 Widget 配置使用formatApiCall(widgets[widget.type].api, { endpoint, ...widget })将{url}、{key}、{endpoint}等占位符替换为实际值拼出最终 URL通过httpProxy发起 HTTP 请求并做响应校验validateWidgetData与错误信息脱敏sanitizeErrorURL。前端侧组件通过 src/utils/proxy/use-widget-api.js 中封装的useSWR拉取数据并为get_activity设置了5000ms5 秒的刷新间隔见 src/widgets/tautulli/component.jsxconst { data: activityData, error: activityError } useWidgetAPI(widget, get_activity, { refreshInterval: 5000, });也就是说只要页面处于打开状态Tautulli Widget 每 5 秒会自动重新请求一次活跃会话数据保证仪表板上的播放状态接近实时。五、渲染行为详解三种展示形态与判断逻辑Tautulli Widget 的渲染组件在 src/widgets/tautulli/component.jsx 中实现其展示逻辑可以根据活跃流数量分为三种形态。5.1 加载态与空态加载中数据尚未返回时渲染 12 行占位符-无活跃流sessions为空数组时显示国际化文案tautulli.no_active英文为 No Active Streams简体中文为暂无播放见 public/locales/en/common.json 与 public/locales/zh-Hans/common.json连接错误请求失败或返回空数据时显示tautulli.plex_connection_error英文 Check Plex Connection简体中文检查Plex连接提示检查 Plex/Tautulli 连通性。5.2 单流双行展开expandOneStreamToTwoRows当expandOneStreamToTwoRows为true默认值且当前恰好只有一个活跃播放流时Widget 使用SingleSessionEntry渲染两行第一行标题行展示流标题并在右侧显示播放决策图标第二行进度行带进度的进度条背景左侧显示播放/暂停图标右侧显示当前观看位置 / 总时长格式为HH:MM:SS或MM:SS。多流时2 个及以上则退化为紧凑的单行模式SessionEntry每行显示状态图标、标题、播放决策图标和当前观看位置不再展示完整进度条与总时长。这个开关的默认值在源码中是这样生效的const expandOneStreamToTwoRows service.widget?.expandOneStreamToTwoRows ! false; // default is true即只有当显式配置为false时才会关闭双行展开不配置即为true。5.3 标题与集数显示enableUser / showEpisodeNumber标题的生成逻辑由generateStreamTitle完成function generateStreamTitle(session, enableUser, showEpisodeNumber) { let stream_title ; const { media_type, parent_media_index, media_index, title, grandparent_title, full_title, friendly_name } session; if (media_type episode showEpisodeNumber) { const season_str S${parent_media_index.toString().padStart(2, 0)}; const episode_str E${media_index.toString().padStart(2, 0)}; stream_title ${grandparent_title}: ${season_str} · ${episode_str} - ${title}; } else { stream_title full_title; } return enableUser ? ${stream_title} (${friendly_name}) : stream_title; }showEpisodeNumber: true当媒体类型为剧集episode时标题显示为剧名: S01 · E05 - 单集标题的格式方便快速定位季/集enableUser: true在标题末尾追加(用户名)其中用户名取自 Tautulli 会话中的friendly_name字段便于在多用户家庭环境中区分谁在观看。5.4 播放决策图标Direct Play / Copy / Transcode每行右侧的图标用于表达 Tautulli 返回的video_decision与audio_decision组合视频/音频决策图标含义均为direct playMdSmartDisplay实心显示器直接播放无任何转码均为copyMdOutlineSmartDisplay描边显示器容器/流复制remux接近无损其他组合BsFillCpuFill/BsCpu涉及转码CPU 参与处理图标语义结合国际化文案tautulli.playing播放中、tautulli.transcoding转码、tautulli.bitrate比特率使用可直观判断当前播放流的资源占用情况。5.5 排序规则获取到会话列表后组件会对sessions按view_offset当前观看位置毫秒进行升序排序后再渲染即观看进度靠前的播放流显示在上面const playing activityData.response.data.sessions.sort((a, b) { if (a.view_offset b.view_offset) return 1; if (a.view_offset b.view_offset) return -1; return 0; });六、测试与验证Widget 行为的自动化保障仓库为 Tautulli Widget 提供了完整的测试可作为理解其行为与验证配置合法性的参考src/widgets/tautulli/widget.test.js通过expectWidgetConfigShape校验 Widget 配置对象api、proxyHandler、mappings等符合项目约定的结构任何字段缺失都会导致测试失败src/widgets/tautulli/component.test.jsx使用vi.mock模拟useWidgetAPI覆盖三类关键场景加载中显示占位行-无活跃会话时显示tautulli.no_active文案单个会话播放时渲染双行展开且时间格式正确如view_offset: 1000毫秒渲染为00:01duration: 2000渲染为00:02。这些测试一方面验证了渲染逻辑的正确性另一方面也侧面印证了本文第五节描述的展示规则。七、常见问题与排错1. Widget 显示检查Plex连接Check Plex Connection该错误对应tautulli.plex_connection_error出现时说明请求 Tautulli 失败或返回数据为空。请依次检查url是否可从运行 Homepage 的主机访问注意不要写成 Plex 的地址而是 Tautulli 的地址key是否复制完整API Key 在Settings Web Interface API中查看Tautulli 服务是否运行正常、端口是否正确。2. 显示暂无播放No Active Streams但 Plex 明明在播放确认 Plex 用户确实在当前活跃播放而非暂停很久或已退出Tautulli 的get_activity接口只返回当前处于活动状态的会话。另外注意 Widget 每 5 秒刷新一次数据可能存在数秒延迟。3. 不想看到用户名 / 不想显示集数分别将enableUser、showEpisodeNumber配置为false或不配置因为默认即false。4. 希望单流时也保持一行将expandOneStreamToTwoRows显式设置为false此时无论活跃流数量多少都使用紧凑单行渲染。八、小结Homepage 的 Tautulli Widget 以实时活跃播放流监控为单一职责配置只需urlkey两个必填项配合enableUser、showEpisodeNumber、expandOneStreamToTwoRows三个可选开关即可适配不同展示偏好。底层通过服务端通用代理调用 Tautulli API v2 的get_activity命令前端每 5 秒刷新并针对 Direct Play / Copy / Transcode 提供直观的图标反馈。若需深入理解实现细节可继续阅读 src/widgets/tautulli/widget.js、src/widgets/tautulli/component.jsx 以及对应的 组件测试。【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考