Finetic：基于Next.js的现代Jellyfin客户端——功能、安装与使用全指南

如果你是Jellyfin用户，正在寻找一个界面更现代、功能更丰富的客户端，那么Finetic或许能满足你的需求。作为一款基于Next.js开发的Jellyfin客户端，它不仅在设计上紧跟潮流，还融入了AI技术，让媒体浏览和播放体验更加智能。接下来，我们将详细介绍Finetic的核心功能、技术架构、安装步骤以及使用方法，帮助你全面了解这款工具。

什么是Finetic？

Finetic是一款现代化的Jellyfin客户端，专为提升媒体浏览和播放体验而设计。它采用Next.js、React等前沿前端技术开发，支持明暗主题切换，还内置了由Google Gemini驱动的AI助手，让你能通过自然语言交互快速找到并播放喜欢的内容。

简单来说，如果你习惯用Jellyfin管理和观看电影、剧集，Finetic可以作为一个更易用、更智能的“前端界面”，连接你的Jellyfin服务器，让整个使用过程更顺畅。

Finetic logo

从界面设计来看，Finetic兼顾了美观与实用性。以下是它在明暗两种主题下的展示（左侧为浅色主题，右侧为深色主题）：

Finetic浅色主题界面 Finetic深色主题界面

Finetic的核心功能

Finetic的设计围绕“便捷”和“智能”展开，无论是媒体管理还是播放体验，都加入了不少实用功能。以下是它的核心特点：

1. 智能导航助手（AI驱动）

Finetic最突出的功能之一是内置的AI聊天助手，由Google Gemini 2.0 Flash提供支持。你可以通过自然语言指令快速完成各种操作，无需手动点击菜单。

比如，你可以直接说：

  • “播放《盗梦空间》”
  • “打开《绝命毒师》”
  • “跳到动作场景”
  • “解释一下现在发生了什么”
  • “这部电影讲了什么？”

这个AI助手不仅能理解简单指令，还能处理模糊描述。例如，当你输入“b99”，它会自动识别为《神烦警探》（Brooklyn Nine-Nine）；说“有蓝色人的电影”，它能定位到《阿凡达》。

2. 功能丰富的媒体播放器

播放器是Finetic的核心模块，支持多种播放方式和实用功能：

  • 灵活的播放模式：支持直接播放（浏览器兼容时）和转码播放（格式不兼容或网络不佳时），会根据设备和网络条件自动选择最优方式。
  • 字幕支持：内置字幕功能，方便观看外语内容。
  • 章节导航：可以直接跳转到视频的不同章节。
  • 跳过片头：自动检测剧集片头，提供“跳过”按钮，直接进入正片。
  • 键盘快捷键：空格（播放/暂停）、左右箭头（快进/后退）、上下箭头（调节音量）、F键（全屏切换），操作更高效。

3. 媒体库管理

Finetic能帮你轻松浏览和整理Jellyfin服务器中的内容：

  • 分类展示电影、电视剧和单集。
  • 支持查看“继续观看”列表，快速回到上次未看完的内容。
  • 可访问“观看清单”，查看收藏或高评分内容。
  • 按类型、演员、导演等维度筛选内容。

4. 主题切换

支持浅色、深色和系统主题三种模式，可根据使用场景（如白天/夜晚）或个人习惯切换，减少视觉疲劳。

Finetic的技术架构

Finetic的流畅体验离不开其背后的技术栈。如果你对技术细节感兴趣，以下是它的核心技术组成：

模块 技术栈
前端框架 Next.js 15、React 19、TypeScript
样式与交互 Tailwind v4、shadcn/ui、Framer Motion
AI功能 Google Gemini 2.0 Flash、AI SDK
状态管理 Jotai（用于全局状态管理）

这些技术的组合确保了Finetic在性能、兼容性和用户体验上的平衡：Next.js提供了服务端渲染能力，让页面加载更快；TypeScript保证了代码的稳定性；Tailwind和shadcn/ui则让界面设计更灵活。

如何开始使用Finetic？

如果你想尝试Finetic，只需按照以下步骤操作。整个过程不复杂，即使是对技术不太熟悉的用户也能完成。

前提条件

在安装Finetic之前，你需要准备这些东西：

  • 安装Node.js 18或更高版本（可在Node.js官网下载）。
  • 一台正在运行的Jellyfin服务器（Finetic需要连接它获取媒体内容）。
  • Google AI API密钥（用于启用AI助手功能，可在Google AI平台申请）。

安装步骤

1. 克隆代码仓库

首先，将Finetic的代码下载到本地。打开终端（Windows用户可用命令提示符或PowerShell，Mac/Linux用户用终端），输入以下命令：

git clone https://github.com/AyaanZaveri/finetic
cd finetic

这一步会将代码仓库复制到你的电脑，并进入项目文件夹。

2. 安装依赖

Finetic需要一些第三方库才能运行，通过以下命令安装：

# 用npm安装
npm install

# 或用yarn
yarn install

# 或用bun（如果已安装）
bun install

选择你熟悉的包管理器即可，等待安装完成（可能需要几分钟，取决于网络速度）。

3. 配置环境变量

AI助手功能需要Google API密钥才能工作，因此需要创建一个环境变量文件：

  1. 在项目根目录（即finetic文件夹）中，新建一个名为.env.local的文件。
  2. 打开文件，输入以下内容，并将your_google_ai_api_key替换为你的实际API密钥：
GOOGLE_GENERATIVE_AI_API_KEY=your_google_ai_api_key

保存文件后，环境变量就配置好了。

启动开发服务器（用于体验和测试）

如果你只是想先体验Finetic，无需部署到服务器，可以启动开发模式：

# 用npm
npm run dev

# 或用yarn
yarn dev

# 或用bun
bun dev

命令执行后，终端会显示服务器地址（通常是http://localhost:3000）。打开浏览器访问这个地址，就能看到Finetic的界面了。

构建生产版本（用于正式使用）

如果想在服务器上部署Finetic，需要先构建生产版本：

# 构建应用
npm run build

# 启动生产服务器
npm run start

构建完成后，Finetic会以更高效的方式运行，适合长期使用。

首次使用设置

第一次打开Finetic时，需要完成几个简单的设置步骤：

  1. 配置Jellyfin服务器：输入你的Jellyfin服务器地址（例如http://192.168.1.100:8096），确保Finetic能连接到你的媒体库。
  2. 登录账号：使用你的Jellyfin用户名和密码登录，验证身份后才能访问媒体内容。
  3. 启用AI功能：如果之前已配置好Google API密钥，AI助手会自动启用；如果没配置，可在设置中补充密钥。

详细使用指南

如何使用AI助手？

AI助手是Finetic的“智能大脑”，学会用它能大幅提升操作效率。

打开AI助手

按下键盘上的⌘ + K（Mac）或Ctrl + K（Windows/Linux），就能调出AI聊天窗口。

AI助手能做什么？

它内置了多种工具，覆盖内容查找、播放控制、场景分析等场景，以下是常用功能分类：

内容发现与搜索
  • searchMedia：按名称或关键词搜索电影、剧集或单集。例如：“搜索科幻电影”。
  • getPeople：查找与媒体相关的人员（导演、演员）。例如：“找汤姆·汉克斯主演的电影”。
  • getGenres：获取媒体库中的所有类型（如动作、喜剧、科幻）。例如：“显示所有可用类型”。
媒体库浏览与管理
  • getMovies：查看最近添加的电影。例如：“显示最近的电影”。
  • getTVShows：查看最近添加的电视剧。例如：“显示最近的剧集”。
  • continueWatching：获取“继续观看”列表。例如：“我之前看到哪了？”。
  • getWatchlist：查看收藏或高评分内容。例如：“显示我的收藏”。
  • getMediaDetails：获取某部作品的详细信息（剧情、演员等）。例如：“《盗梦空间》讲了什么？”。
  • getSeasons：查看某部剧集的季数。例如：“《老友记》有多少季？”。
  • getEpisodes：查看某季的具体集数。例如：“《绝命毒师》第3季有哪些集？”。
播放与导航
  • navigateToMedia：跳转到某部作品的页面。例如：“去《甄嬛传》的页面”。
  • playMedia：直接播放某部作品。例如：“播放《星际穿越》”。
字幕分析（播放时可用）
  • skipToSubtitleContent：根据描述跳转到对应场景（无需精确匹配字幕）。例如：“跳到他们讨论计划的地方”。
  • explainScene：分析当前时间点的字幕，解释场景内容。例如：“现在发生了什么？”。
  • analyzeMedia：通过全文字幕分析作品的剧情、角色等。例如：“这部电影的主题是什么？”。
应用控制
  • themeToggle：切换主题（浅色/深色/系统）。例如：“切换到深色模式”。

智能字幕功能（播放时）

当你正在播放视频时，AI助手能利用字幕信息提供更精准的服务：

  • 场景导航：不用手动拖动进度条，直接说“跳到吵架的场景”“去主角第一次出现的地方”，AI会分析字幕找到对应时间点。
  • 场景解释：如果错过某些剧情，可问“刚才发生了什么？”“这个人是谁？”，AI会基于当前字幕内容解释。
  • 内容分析：想快速了解作品？可以问“这部电影的结局是什么？”“这集的主要冲突是什么？”，AI会通过全文字幕总结。

媒体播放器的使用技巧

点击任何媒体 item 即可开始播放，播放器的这些功能值得一试：

  • 播放模式选择：Finetic会自动判断是否直接播放（适合格式兼容、网络好的情况）或转码播放（适合格式不支持或网络差的情况），无需手动设置。
  • 跳过片头：播放剧集时，如果顶部出现“跳过片头”按钮，点击即可直接跳过冗长的片头。
  • 快捷键操作：记住这些快捷键能让操作更顺手：

    • 空格：播放/暂停
    • 左箭头：后退5秒
    • 右箭头：前进5秒
    • 上箭头：音量增大
    • 下箭头：音量减小
    • F键：切换全屏

常见问题（FAQ）

1. 没有Google AI API密钥，能使用Finetic吗？

可以，但AI助手相关功能（如语音指令、智能搜索）无法使用。你仍可以正常浏览媒体库和播放内容。

2. Finetic支持哪些设备？

Finetic是基于网页的应用，只要设备能运行现代浏览器（如Chrome、Edge、Safari），就能使用，包括电脑、平板和手机。

3. 为什么连接不上Jellyfin服务器？

可能的原因：

  • 服务器地址输入错误（确保包含正确的IP和端口，如http://192.168.1.100:8096）。
  • Jellyfin服务器未开启或网络不可达（检查服务器是否正常运行，设备是否在同一网络）。
  • 防火墙阻止了连接（尝试关闭设备或服务器的防火墙，或添加端口例外）。

4. 播放视频时卡顿怎么办？

  • 检查网络速度：如果网络不稳定，Finetic可能会自动切换到转码模式，降低画质以保证流畅性。
  • 手动选择转码：在播放设置中，尝试降低视频分辨率或比特率。
  • 确保服务器性能足够：转码需要服务器有一定的CPU性能，如果服务器配置较低，可能会导致卡顿。

5. 如何更新Finetic到最新版本？

在项目文件夹中，执行以下命令：

git pull  # 拉取最新代码
npm install  # 安装可能的新依赖
npm run dev  # 重新启动开发服务器（或构建生产版本）

6. 可以在Finetic中管理Jellyfin的媒体库吗（如添加/删除文件）？

目前不能。Finetic主要是一个客户端，用于浏览和播放内容，媒体库的管理仍需在Jellyfin服务器中进行。

如何为Finetic做贡献？

如果你觉得Finetic有改进空间，可以通过以下方式参与贡献：

  • 报告bug或提出功能建议：在GitHub仓库的Issues页面提交。
  • 提交代码：如果你熟悉前端开发，可以fork仓库，修改代码后提交Pull Request。
  • 完善文档：帮助优化使用指南或技术说明。

如果想支持开发者，也可以通过Ko-fi平台捐赠：

Buy Me a Coffee at ko-fi.com

许可证信息

Finetic基于GNU General Public License v3.0许可证发布，这意味着你可以自由使用、修改和分发该软件，但必须保留原许可证信息，并在修改后以相同许可证发布。详细条款可查看项目中的LICENSE文件。

通过以上内容，相信你对Finetic有了全面的了解。无论是AI助手带来的智能交互，还是播放器的实用功能，它都在努力让Jellyfin的使用体验更上一层楼。如果你刚好需要一个现代化的Jellyfin客户端，不妨按照安装步骤试试，或许会给你带来惊喜。