当大部分用户还在抱怨网络延迟影响观影体验时，一套能让Jellyfin客户端同时驾驭云端与本地媒体的架构方案，才是真正的工程解药。这不仅仅是功能叠加，而是一种设计理念的升级。
为什么需要为Jellyfin客户端添加本地媒体支持？
你是否遇到过这样的窘境？精心开发的Jellyfin客户端界面精美、功能强大，却严重依赖网络：一旦网络卡顿，观影体验就大打折扣；服务器宕机，整个应用几乎瘫痪；离线状态下，连一个本地视频都无法播放。这感觉不像是开发了一个媒体播放器，更像是做了一个“网络浏览器”——有网能用，没网抓瞎。
那么，有人可能会问：直接双击本地视频文件用系统播放器打开不就行了吗？为什么非要集成到Jellyfin客户端里？
这个问题很好。如果只是偶尔观看单个视频，确实无需集成。但当你追求一致的媒体管理和播放体验时，独立的文件播放器就显得力不从心了：
| 使用独立文件播放器 |
集成Jellyfin客户端本地媒体库 |
| 需要手动在文件系统中查找文件 |
自动扫描索引，媒体库中直接浏览，无需记忆路径 |
| 难以对大量媒体文件进行批量管理 |
支持统一分类、标签筛选和全局搜索，集中管理所有媒体 |
| 媒体文件分散在各个文件夹 |
提供统一的本地媒体资源访问入口和管理中心 |
| 播放历史、进度和收藏无法保存 |
完整记录播放历史、进度、收藏和评分 |
| 必须记住每个文件的具体位置 |
通过丰富的元数据（如片名、类型、时长）快速定位媒体 |
| 仅能播放本地存储的文件 |
既能播放本地文件，也能无缝连接云端Jellyfin服务器 |
| 完全离线使用 |
离线时使用本地媒体，联网时访问云端内容 |
| 存储容量受限于本地硬盘 |
本地+云端混合存储，理论上容量无限扩展 |
问题的核心在于，我们过去可能将Jellyfin客户端定位为一个纯粹的“网络客户端”，而非一个既能连接云端、又能管理本地的“全功能媒体中心”。真正缺失的不是更快的网络带宽，而是一套支持云端与本地媒体无缝切换、统一管理的混合架构方案。
抽象的理论都是虚的，能亲手把本地媒体库作为一个可编程、可调试的核心组件集成到你的Jellyfin客户端里，这才是构建强大媒体应用的关键资产。
第一阶段：核心架构拆解：数据库与扫描器
别被复杂的架构图吓到。我们直接用一个表格，将两个核心组件的本质讲清楚。
| 维度 |
LocalMediaDatabase (本地媒体数据库) |
LocalMediaScanner (本地媒体扫描器) |
| 它是什么 |
一套基于 SQLite 的数据存储方案。 定义了媒体文件如何以结构化、可检索的形式持久化存储在本地设备上。 |
一套文件系统遍历与解析工具。 定义了如何高效、递归地发现、识别并提取本地媒体文件的元数据。 |
| 核心价值 |
解决“存储与检索”问题。 让按类型、名称、时间等条件查询媒体，变得像执行SQL语句一样简单、标准。 |
解决“发现与识别”问题。 确保硬盘中每一个媒体文件都能被系统“看见”，并将其关键信息（如时长、类型）提取出来。 |
| 一个比喻 |
媒体文件的“弹药库”（记录着“电影A存放在路径X，时长Y分钟”）。 |
在硬盘丛林中的“侦察兵”（负责汇报“在 /Downloads/ 目录下发现一部新视频”）。 |
| 开发者的角色 |
军需官：设计并维护弹药库的结构，确保分类清晰、存取高效有序。 |
侦察队长：制定扫描策略，确保搜索无死角，并能准确识别目标。 |
💡 核心洞见：
数据库让你能够找到已知的媒体（存储与索引），而扫描器让你知道哪里有媒体、有多少、是什么类型、以及是否有新增。数据库是货架，扫描器是采购员。没有结构良好的数据库，扫描只是无效的忙碌；没有高效的扫描器，数据库只是一个空架子。
第二阶段：实战代码实现：从原理到可运行代码
理论是基础，能运行的代码才是硬道理。假设我们要为现有的Jellyfin客户端（假设基于Qt框架）增加扫描和播放本地媒体文件的能力。
1. 定义数据库结构（构建“弹药库”）
首先，需要一个 SQLite 数据库来存储媒体信息。核心是设计贴合媒体属性的表结构。
// localmediadatabase.h 核心实现
class LocalMediaDatabase {
public:
bool initialize(const QString &dbPath) {
m_db = QSqlDatabase::addDatabase("QSQLITE");
m_db.setDatabaseName(dbPath);
if (!m_db.open()) return false;
// 创建媒体信息表
QSqlQuery query;
return query.exec(
"CREATE TABLE IF NOT EXISTS media ("
"id TEXT PRIMARY KEY, "
"name TEXT NOT NULL, "
"type TEXT NOT NULL, " // video/audio/image
"path TEXT NOT NULL UNIQUE, "
"thumbnail TEXT, "
"duration INTEGER, " // 秒
"size INTEGER, " // 字节
"created_at DATETIME DEFAULT CURRENT_TIMESTAMP"
")"
);
}
bool addMedia(const MediaItem &item) {
QSqlQuery query;
query.prepare("INSERT OR REPLACE INTO media VALUES (?, ?, ?, ?, ?, ?, ?)");
query.addBindValue(item.id);
query.addBindValue(item.name);
query.addBindValue(item.type);
query.addBindValue(item.path);
query.addBindValue(item.thumbnail);
query.addBindValue(item.duration);
query.addBindValue(item.size);
return query.exec();
}
QList<MediaItem> queryMedia(const QString &type = "") {
QList<MediaItem> items;
QSqlQuery query;
if (type.isEmpty()) {
query.exec("SELECT * FROM media ORDER BY created_at DESC");
} else {
query.prepare("SELECT * FROM media WHERE type = ? ORDER BY created_at DESC");
query.addBindValue(type);
query.exec();
}
while (query.next()) {
MediaItem item;
item.id = query.value("id").toString();
item.name = query.value("name").toString();
item.type = query.value("type").toString();
item.path = query.value("path").toString();
item.thumbnail = query.value("thumbnail").toString();
item.duration = query.value("duration").toInt();
item.size = query.value("size").toLongLong();
items.append(item);
}
return items;
}
private:
QSqlDatabase m_db;
};
2. 实现媒体扫描器（派遣“侦察兵”）
扫描器需要异步工作，避免阻塞UI，并及时通知进度。
// localmediascanner.h 核心实现
class LocalMediaScanner : public QObject {
Q_OBJECT
public:
explicit LocalMediaScanner(QObject *parent = nullptr) : QObject(parent) {}
void scanDirectory(const QString &path) {
QThreadPool::globalInstance()->start([this, path]() {
performScan(path);
});
}
signals:
void scanProgress(int percentage);
void mediaFound(const MediaItem &item);
void scanFinished();
private:
void performScan(const QString &path) {
QDir dir(path);
QStringList filters;
// 支持的多媒体文件扩展名
filters << "*.mp4" << "*.mkv" << "*.avi" << "*.mov" << "*.flv" // 视频
<< "*.mp3" << "*.flac" << "*.wav" << "*.ogg" << "*.aac" // 音频
<< "*.jpg" << "*.png" << "*.gif" << "*.bmp"; // 图片
dir.setNameFilters(filters);
dir.setFilter(QDir::Files | QDir::NoDotAndDotDot);
QFileInfoList fileList = dir.entryInfoList();
int totalFiles = fileList.size();
int processedFiles = 0;
for (const QFileInfo &fileInfo : fileList) {
MediaItem item;
item.id = QUuid::createUuid().toString();
item.name = fileInfo.baseName();
item.path = fileInfo.absoluteFilePath();
item.size = fileInfo.size();
// 根据文件后缀判断媒体类型
QString suffix = fileInfo.suffix().toLower();
if (QStringList({"mp4", "mkv", "avi", "mov", "flv"}).contains(suffix)) {
item.type = "video";
// 提取视频时长（需集成FFmpeg库）
item.duration = extractVideoDuration(item.path);
} else if (QStringList({"mp3", "flac", "wav", "ogg", "aac"}).contains(suffix)) {
item.type = "audio";
// 提取音频元数据（需集成TagLib库）
item.duration = extractAudioDuration(item.path);
} else {
item.type = "image";
item.duration = 0;
}
emit mediaFound(item);
// 更新扫描进度
processedFiles++;
emit scanProgress(static_cast<int>((processedFiles * 100) / totalFiles));
}
emit scanFinished();
}
int extractVideoDuration(const QString &path) {
// 使用FFmpeg API提取视频时长
// 此处为简化示例，实际需调用FFmpeg库
Q_UNUSED(path)
return 0; // 应返回秒数
}
int extractAudioDuration(const QString &path) {
// 使用TagLib API提取音频时长
// 此处为简化示例，实际需调用TagLib库
Q_UNUSED(path)
return 0; // 应返回秒数
}
};
✅ 至此，核心数据层功能已完成。 你的应用现在有能力扫描本地媒体文件并将其信息存储到数据库中。但这仅仅达到了“能用”的水平。
3. 集成到UI：实现“云端/本地”无缝切换（打造“指挥系统”）
现在需要UI层的配合。当用户点击“切换到本地媒体”时，应用应该流畅地展示本地内容，而不是一个空列表。
// mediapage.h 核心修改
class MediaPage : public QWidget {
Q_OBJECT
public:
explicit MediaPage(QWidget *parent = nullptr);
enum class SourceMode { Remote, Local };
private slots:
void toggleSource();
void onMediaFound(const MediaItem &item);
void onScanProgress(int percentage);
void onScanFinished();
private:
void loadFromSource(SourceMode mode);
void setupUI();
SourceMode m_sourceMode = SourceMode::Remote;
QPushButton *m_sourceToggle;
QListWidget *m_mediaList;
QLabel *m_statusLabel;
LocalMediaDatabase *m_localDatabase;
LocalMediaScanner *m_localScanner;
JellyfinApiClient *m_jellyfinApi; // 假设已存在的Jellyfin API客户端
};
// mediapage.cpp 部分实现
void MediaPage::setupUI() {
// ... 其他UI组件的初始化
// 添加媒体源切换按钮
m_sourceToggle = new QPushButton("切换到本地媒体", this);
connect(m_sourceToggle, &QPushButton::clicked, this, &MediaPage::toggleSource);
// 初始化本地媒体组件
m_localDatabase = new LocalMediaDatabase(this);
m_localScanner = new LocalMediaScanner(this);
connect(m_localScanner, &LocalMediaScanner::mediaFound,
this, &MediaPage::onMediaFound);
connect(m_localScanner, &LocalMediaScanner::scanProgress,
this, &MediaPage::onScanProgress);
connect(m_localScanner, &LocalMediaScanner::scanFinished,
this, &MediaPage::onScanFinished);
// 初始化数据库路径
QString dbPath = QStandardPaths::writableLocation(QStandardPaths::AppDataLocation) + "/media.db";
m_localDatabase->initialize(dbPath);
}
void MediaPage::toggleSource() {
if (m_sourceMode == SourceMode::Remote) {
m_sourceMode = SourceMode::Local;
m_sourceToggle->setText("切换到Jellyfin服务器");
loadFromSource(SourceMode::Local);
} else {
m_sourceMode = SourceMode::Remote;
m_sourceToggle->setText("切换到本地媒体");
loadFromSource(SourceMode::Remote);
}
}
void MediaPage::loadFromSource(SourceMode mode) {
m_mediaList->clear();
if (mode == SourceMode::Local) {
// 从本地数据库加载媒体列表
QList<MediaItem> items = m_localDatabase->queryMedia();
for (const MediaItem &item : items) {
QListWidgetItem *listItem = new QListWidgetItem(item.name);
listItem->setData(Qt::UserRole, QVariant::fromValue(item));
m_mediaList->addItem(listItem);
}
if (items.isEmpty()) {
m_statusLabel->setText("未找到本地媒体文件，请先扫描媒体文件夹。");
} else {
m_statusLabel->setText(QString("已加载 %1 个本地媒体文件").arg(items.size()));
}
} else {
// 切换到远程模式，调用现有的Jellyfin API加载云端媒体库
m_jellyfinApi->loadMediaLibrary();
}
}
⚠️ 关键提示：
如果只实现了数据库和扫描器，那你只是一个“媒体存储引擎开发者”。用户无法方便地浏览和播放这些媒体。只有构建了完整的UI交互层，本地媒体库才能真正转化为用户手中的“私人影院”。
第三阶段：架构价值：从“网络依赖者”到“混合媒体中心”
完成上述实现后，你的Jellyfin客户端将实现质的飞跃：
- ❌ 网络依赖级：只能连接远程Jellyfin服务器，网络即生命线，离线即瘫痪。
- ✅ 混合媒体中心级：
- 无缝切换：通过一个按钮，在云端媒体库和本地媒体库之间即时切换，无需重启应用。
- 统一体验：无论媒体来自云端还是本地，都使用同一套播放器、同一套界面控件和交互逻辑。
- 智能同步（进阶）：本地产生的播放记录、收藏状态，可以在网络恢复后同步到Jellyfin服务器。
- 离线可用：在网络中断或服务器不可用时，自动降级使用本地媒体库，保障核心播放功能不中断。
记住：数据库决定了你“存储与组织”媒体信息的能力边界，而扫描器决定了你“发现与吸纳”新内容的能力上限。 前者是系统的骨架，后者是系统的感官，二者结合，才能构建出健壮的本地媒体支持功能。
通过这套基于 Qt 和 SQLite 的 C++ 实现方案，我们不仅为Jellyfin客户端增加了离线播放能力，更重要的是引入了一种灵活的、可扩展的混合媒体架构思想。技术方案的选型与实现细节，欢迎在云栈社区与更多开发者深入探讨。下一步，或许可以继续深入播放器内核、元数据刮削器或者跨平台同步等更有挑战的模块。
最后，这个问题值得思考：你希望你的Jellyfin客户端永远是一个依赖网络的“终端”，还是决心将其打造为一个随时随地、无论在线与否都能提供完整服务的“个人媒体中心”？
发表于 昨天 06:56
|
查看: 2|
回复: 0
