接口参考手册

这个参考手册描述了 feeluown 的几大组成部分，各组成部分的主要模块， 以及模块的相对稳定接口。

播放模块

播放模块由两部分组成：播放列表(Playlist)和播放器(Player)。

播放列表维护了一个媒体资源集合，并提供若干资源获取接口，播放器通过接口获取资源， 然后进行播放。这些接口包括： current_song, next_song, previous_song 。

播放列表吐资源给播放器的时候，是有一定的顺序的，我们称之为回放模式(PlaybackMode)。 回放模式有四种：单曲循环；顺序；循环；随机。上述三个资源访问接口吐资源的顺序都会受回放模式影响。

当播放列表 current_song 变化时，它会发出 song_changed 信号，播放器会监听该信号， 从而播放、停止（song 为空时）或者切换歌曲。播放歌曲时，播放器的状态(State)会发生变化， 当没有歌曲播放的时候，播放器为停止(stopped)状态，有歌曲播放的时候，为正在播放状态。 当一首歌开始播放后，播放器会发出 media_changed 信号， 当一首歌曲播放完毕时，播放器会发出 song_finished 信号。

播放列表和播放器之间的调用关系如下:

Playlist                                         (Mpv)Player

    current_song.setter ---[song_changed]---> play_song
       ^                                      |
       |                                      | <song==None>
       |<- play_song                          |--------------> stop
       |<- play_next/play_previous            |
       |<- play_next <-|                  prepare_media
       |<- replay    <-| <mode==one_loop>     |
                       |                      v
                       |                    play ---[media_changed]--->
                 [song_finished]
                       |
                       |
                       ---- event(END_FILE)
                                   ^
                                   |
                                MpvPlayer

通用管理模块

feeluown.task.is_in_loop_thread()

check if current thread has event loop

class feeluown.task.TaskKind

An enumeration.

preemptive = 'preemptive'

preemptive task

cooperative = 'cooperative'

cooperative task

class feeluown.task.PreemptiveTaskSpec(mgr, name)

Preemptive task specification (threadsafe)

bind_coro(coro)

run the coroutine and bind the task

it will cancel the previous task if exists

Returns:asyncio.Task

bind_blocking_io(func, *args)

run blocking io func in a thread executor, and bind the task

it will cancel the previous task if exists

Returns:asyncio.Task

class feeluown.task.TaskManager(app)

named task manager

Usage:

async def fetch_song():
     pass

task_name = 'unique-name'

task_spec = task_mgr.get_or_create(task_name, TaskType.preemptive)
task = task_spec.bind_coro(fetch_song())

get_or_create(name, kind=<TaskKind.preemptive: 'preemptive'>)

get task spec, it will be created if not exists

Parameters:

• name – task identifier(name)
• kind – TaskKind

TODO: client should register first, then get by name

GUI 相关管理模块

Note

目前，大部分 GUI 组件的接口都不稳定，我们在实现插件时，如果需要从操作 GUI 组件， 请调用以下模块的接口。如果我们想实现的功能通过以下接口在暂时实现不了， 请和 @cosven 联系。

class feeluown.gui.uimodels.my_music.MyMusicUiManager(app)

Note

目前，我们用数组的数据结构来保存 items，只提供 add_item 和 clear 方法。 我们希望，MyMusic 中的 items 应该和 provider 保持关联。provider 是 MyMusic 的上下文。

而 Provider 是比较上层的对象，我们会提供 get_item 这种比较精细的控制方法。

播放列表管理

class feeluown.gui.uimodels.playlist.PlaylistUiItem(obj=None, **kwargs)

根据目前经验，播放列表的相关操作最基本的就是几个：

• 创建、删除
• 添加、移除歌曲
• 重命名
• 点击展示这个歌单

这些操作对各平台的播放列表、歌单来说，语义都是一致的， 所以 PlaylistUiItem 暂时不提供 clicked 等操作信号。

GUI 组件

class feeluown.gui.widgets.login.LoginDialog

Base class for login dialogs

login_succeed

login succeed signal

class feeluown.gui.widgets.login.CookiesLoginDialog(uri: str = None, required_cookies_fields=None)

CookiesLoginDialog provides a text edit area and a login button. User firstly fill in the text edit area with cookies. User can then click the login button. The clicked signal is connected to login().

Cookies can be in text or json format. User can copy cookies from web browser like Chrome or Firefox. Cookies copied from firefox are in json format and cookies copied from Chrome are in text format.

Subclass MUST implement four methods.

• setup_user()
• user_from_cookies()
• load_user_cookies()
• dump_user_cookies()

One usage example: feeluown-qqmusic.

get_cookies()

Parse the content in text edit area

Returns:return None when the content is invalid Return type:dict or None

show_hint(text, color=None)

Show hint message on dialog

Parameters:color (string) – red for error, orange for warning, green for success

autologin()

Try to load user cookies and login with it

Generally, you can call this method after dialog is shown.

setup_user(user)

Setup user session

load_user_cookies()

Load user cookies from somewhere

Load the cookies that is dumped before. If the load processing failed, just return None.

Returns:cookies in dict format Return type:dict or None

dump_user_cookies(user, cookies)

Dump user cookies to somewhere

Generally, you can store the cookies in FeelUOwn data directory with specifical filename.

login()

Login with cookies

Read cookies that has been filled in and create a user from it. If succeed, the login_succeed signal will be emit. If failed, show specific error message on the dialog based on the exception.

user_from_cookies(cookies)

Create a user model from cookies dict

Return type:feeluown.models.UserModel

异常

HELP: I do not know how to design exception classes, as a result, these interfaces can be changed frequently.

exception feeluown.excs.FuoException

exception feeluown.excs.LibraryException

exception feeluown.excs.ProviderIOError(message='', provider=None)

Read/write data from/to provider failed

currently, all providers use requests to send http request, and many Requestexception are not catched, so ProviderIOError inherit RequestException.

exception feeluown.excs.CreateReaderFailed(message='', provider=None)

(DEPRECATED) use ProviderIOError instead

exception feeluown.excs.ReaderException(message='', provider=None)

(DEPRECATED) use ProviderIOError instead

exception feeluown.excs.ReadFailed(message='', provider=None)

(DEPRECATED) use ProviderIOError instead

exception feeluown.excs.ResourceNotFound

exception feeluown.excs.ProviderAlreadyRegistered

exception feeluown.excs.ProviderNotFound

exception feeluown.excs.ModelNotFound

Model is not found

For example, a model identifier is invalid.

New in version 3.7.7.

exception feeluown.excs.NotSupported

Provider does not support the operation

exception feeluown.excs.MediaNotFound

exception feeluown.excs.NoUserLoggedIn

(DEPRECATED) return None when there is no user logged in