配置文件

类似 Vim 的 .vimrc 、Emacs 的 init.el ，feeluown 也有自己的配置文件 .fuorc 。

fuorc 文件是一个 Python 脚本，它位于 ~/.fuorc ，我们可以在其中使用任意 Python 语法。 feeluown 启动时，第一步就是加载并解析该配置文件，结合 Python 的灵活性，意味着你可以对 feeluown 的行为进行完完全全的控制。通常，你可以在配置文件中作以下事情：

配置选项
功能定制

一个🌰

一个 fuorc 文件示例:

import os

# 自定义配置
config.THEME = 'dark'
config.COLLECTIONS_DIR = '~/Dropbox/public/music'
config.AUDIO_SELECT_POLICY = '>>>'


# 一个小功能：切换歌曲时，发送系统通知
def notify_song_changed(song):
    if song is not None:
        title = song.title_display
        artists_name = song.artists_name_display
        song_str = f'{title}-{artists_name}'
        os.system(f'notify-send "{song_str}"')

when('app.playlist.song_changed', notify_song_changed)

# 让编辑器识别这是一个 Python 文件
#
# Local Variables:
# mode: python
# End:
#
# vim: ft=python

配置选项

通用配置项如下

名称	类型	默认值	描述
RPC_PORT	`int`	`23333`	RPC 服务端口
PUBSUB_PORT	`int`	`23334`	PUBSUB 服务端口
ALLOW_LAN_CONNECT	`bool`	`False`	是否可以从局域网连接 RPC 服务
THEME	`str`	`auto`	auto/light/dark
COLLECTIONS_DIR	`str`	`''`	本地收藏所在目录
LOG_TO_FILE	`bool`	`True`	将日志输出到文件中
AUDIO_SELECT_POLICY	`str`	`hq<>`	`feeluown.media.Quality.SortPolicy`
VIDEO_SELECT_POLICY	`str`	`hd<>`	`feeluown.media.Quality.SortPolicy`
NOTIFY_ON_TRACK_CHANGED	`bool`	`False`	切换歌曲时显示桌面通知
NOTIFY_DURATION	`int`	`3000`	桌面通知保留时长(ms)
PROVIDERS_STANDBY	`list`	`None`	候选歌曲提供方（默认：所有提供方）
OPENAI_API_KEY	`str`	`''`	OpenAI API Key
OPENAI_API_BASEURL	`str`	`''`	OpenAI API Base URL
OPENAI_MODEL	`str`	`''`	大模型名字
AI_RADIO_PROMPT	`str`	`...`	AI Radio 功能的 PROMPT

实验特性的配置项

名称	类型	默认值	描述
ENABLE_WEB_SERVER	`bool`	`False`	开启 WEB 服务
WEB_PORT	`int`	`23332`	WEB 服务端口
ENABLE_NEW_HOMEPAGE	`bool`	`False`	开启新版主页
ENABLE_MV_AS_STANDBY	`bool`	`True`	使用 MV 作为歌曲资源
PLAYBACK_CROSSFADE	`bool`	`False`	开启淡入淡出
PLAYBACK_CROSSFADE_DURATION	`int`	`500`	淡入淡出持续时间
ENABLE_YTDL_AS_MEDIA_PROVIDER	`int`	`False`	使用 YTDL 作为媒体资源提供方
YTDL_RULES	`list`	`None`	YTDL 的命中规则

MPV 播放器配置项 (使用 MPV 做为播放引擎时生效)

名称	类型	默认值	描述
MPV_AUDIO_DEVICE	`str`	`auto`	MPV 播放设备

你可以查看下述函数的源代码来查看完整列表。

AI 助手配置

要使用 AI 助手，你需要首先做两件事

确保已经安装了 OpenAI 的 Python 包
并且自己有 OpenAI/DeepSeek/Kimi/豆包/智谱AI 等大模型平台（任意一个）的的 API Key

安装 OpenAI 的 Python 包比较简单，如果你是使用 pipx 安装的，你可以运行:

pipx inject feeluown openai

如果你使用的是 Linux 系统包管理器，你只需要在系统环境中安装 openai 包即可。

获取 API Key 的方法需要参考各个 AI 平台方的文档。以 DeepSeek 为例，你需要在 DeepSeek “API 开放平台”注册并申请一个 API KEY。然后在 ~/.furoc 中进行如下配置。

# deepseek
config.OPENAI_API_BASEURL = 'https://api.deepseek.com'
config.OPENAI_MODEL = 'deepseek-chat'
config.OPENAI_API_KEY = '---API KEY---'

# import os

# 豆包
# config.OPENAI_API_BASEURL = 'https://ark.cn-beijing.volces.com/api/v3'
# config.OPENAI_MODEL = 'ep-20250202091715-vwjw2'
# config.OPENAI_API_KEY = os.environ.get('ARK_API_KEY', '')

# kimi
# config.OPENAI_API_BASEURL = 'https://api.moonshot.cn/v1'
# config.OPENAI_MODEL = 'moonshot-v1-8k'
# config.OPENAI_API_KEY = os.environ.get('MOONSHOT_API_KEY', '')

功能定制

feeluown 使用 Python 的 exec 方法来加载（执行）配置文件。执行时，会暴露 config 对象和部分函数（如 add_hook, rm_hook 等）到这个作用域中。通过 add_hook （这个函数有个别名是 when ），你可以对程序大部分事件进行监听。

常见的事件有

app.player.metadata_changed 歌曲元信息变化时（通常发生于歌曲切换时）
app.initialized 应用初始化完毕（未启动）
app.started 应用已经启动
app.ui.songs_table.about_to_show_menu 右键显示歌曲菜单

你可以参考示例 cosven-fuorc

函数

函数的文档可以参考