Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/keybindings.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ entries, a status message tells you which key to press.
| `Ctrl+Z` | Undo the last playlist or queue change |
| `o` | Open file browser |
| `b` `Esc` | Back to provider |
| `!` | Plugin actions for the active provider |

In full and compact playback layouts, the first `Tab` from the playlist focuses
Source (`SRC`); `Shift+Tab` starts at Speed when it is visible. Source is skipped
Expand Down
90 changes: 88 additions & 2 deletions docs/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -291,6 +291,30 @@ The callback can return a string. The CLI client prints it. Invoke commands from

List registered commands with `cliamp plugins commands`. A command can run for up to 5 minutes before it times out. cliamp also stops a command when its IPC job is canceled and when cliamp quits.

### `p:action{...}` - plugin action pane (requires `permissions = {"ui"}`)

The `!` key opens a pane with the actions the loaded plugins registered for the
active provider. An action can run immediately or ask for one line of text
first. `provider` limits it to a provider, by name.

```lua
p:action{
key = "!", -- optional, default "!"
id = "send", -- unique per plugin
label = "Send message",
description = "Ask the bot for a track",
provider = "Telegram", -- optional
prompt = "Message", -- optional: ask for text first
on_submit = function(text) ... end,
}
```

Actions are namespaced by plugin, so two plugins can use the same `id`.
`p:action` returns `true`, or `false, reason` when the UI permission is missing
or the id is already registered. The action pane filters by provider and by the
text typed in the pane. An action with `prompt` runs `on_submit` with the text;
without it, `on_submit` gets an empty string.

## Lua API

All APIs are in the global `cliamp` table.
Expand Down Expand Up @@ -358,21 +382,22 @@ cliamp.queue.has_next() --> true when a playable track follows in play order

-- mutate (requires "control")
cliamp.queue.add(path) -- resolve a file/dir/URL and append
cliamp.queue.insert(index, track) --> true | nil, err -- insert at index
cliamp.queue.add(track) --> true | nil, err -- append a track table as given
cliamp.queue.jump(index) -- make index current and play it
cliamp.queue.remove(index) -- remove the track at index
cliamp.queue.move(from, to) -- swap the tracks at from and to
```

`add`, `remove`, and `move` follow the rules of the `Shift+Up`, `Shift+Down`,
`add`, `insert`, `remove`, and `move` follow the rules of the `Shift+Up`, `Shift+Down`,
and `x` keys and of IPC:

- While shuffle is on, `move` changes nothing.
- When the queue mirrors a saved local playlist, `move` saves the new order to
that playlist. `remove` removes the track from it too. When that save fails,
the edit changes nothing. Favorites is not a playlist file, so an edit of a
loaded Favorites list changes only the queue.
- `add`, `move`, and `remove` record no undo. After one of them, `Ctrl+Z` does
- `add`, `insert`, `move`, and `remove` record no undo. After one of them, `Ctrl+Z` does
not undo the last TUI edit, because that undo would drop the new change.
- While the queue mirrors a saved local playlist, `remove` does not remove a
track that a directory source of that playlist supplies. A removal of the
Expand Down Expand Up @@ -405,6 +430,53 @@ It returns `true`, or `nil` and an error message when the table is invalid (for
example, a missing path or a title that is not a string) or when the plugin
lacks the `control` permission. An HTTP URL is always marked as a stream.

### cliamp.provider (requires permissions)

`cliamp.provider.current()` returns the provider and the playlist context:

```lua
{
name = "Telegram",
playlist_id = "u:1:2", playlist_name = "DeezLoad",
selection_id = "u:1:2", selection_name = "DeezLoad",
}
```

`playlist_id` is the playlist open in the pane; `selection_id` is the row under
the cursor. Either can be empty. `name` is the same string the provider uses in
the UI.

`cliamp.provider.call(action, params[, options])` calls a provider action.
Reads need `permissions = {"provider"}`; actions that change the remote account
need `permissions = {"provider-send"}`. The provider must implement
`provider.ChatCommander`; a provider without it returns an error.

```lua
-- block until the bot replies, or return the error
local reply, err = cliamp.provider.call("telegram.ask", {
chat = chat,
text = "/search daft punk",
timeout = 60,
})

-- keep the UI responsive while a bot takes its time
cliamp.provider.call("telegram.ask", {chat = chat, text = text}, {
on_reply = function(reply, err) ... end,
timeout = 90,
})
```

Options are `on_reply = function(result, err)` and `timeout = seconds` (default
60). With `on_reply` the call runs off the UI goroutine and delivers the result
to the callback; use it for calls that wait for a bot. Without it the call
blocks the Lua hook and returns the result. A key binding has a five-second
budget, so a waiting call from a key binding needs `on_reply`.

Telegram actions at this layer are `telegram.commands` (the commands a bot
advertises), `telegram.send` (send text and return the message id),
`telegram.ask` (send and wait for the reply), `telegram.reply` (wait for the
next message after an id), and `telegram.callback` (press an inline button).

### cliamp.http

```lua
Expand Down Expand Up @@ -681,6 +753,20 @@ Returns true when the request was accepted. With no interactive UI (headless
mode) it returns an error. Closing the selector calls `on_cancel` when given, or
`on_select(-1)` otherwise.

```lua
cliamp.ui.input{
title = "Message",
placeholder = "/search ...",
value = "", -- optional
on_submit = function(text) ... end,
on_cancel = function() ... end, -- optional, Esc
}
```

`ui.input` asks for one line of text. `Enter` calls `on_submit` with the text;
`Esc` calls `on_cancel` when given. It returns true when the request was
accepted; headless mode returns an error.

### cliamp.vis

```lua
Expand Down
14 changes: 14 additions & 0 deletions docs/telegram.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,20 @@ screen, desktop widgets) as a `data:` URL.
| `buffer_mb` | no | Megabytes buffered before playback (default 1) |
| `session_file` | no | Session path (default `~/.local/share/cliamp/telegram.session`) |

## Bot chats

A chat with a bot is a normal playlist: the provider lists its audio documents
and plays them. A plugin can also write into that chat: send a command as the
signed-in user, wait for the bot's reply, or press an inline button. The write
actions live in the plugin API (`cliamp.provider.call`), not in a fixed key, so
the plugin decides the prompt and how to show the reply. See
[Plugins](plugins.md) and the bundled `telegram-bot.lua`.

Writes use the same MTProto session as reads and act as the signed-in user. A
bot sees a normal message from you; a command sent to a group is visible to
every member. Keep the session file private: it can send messages and press
buttons on your behalf.

## Limits

- One account: the provider browses the dialogs of the signed-in user.
Expand Down
20 changes: 19 additions & 1 deletion external/telegram/provider.go
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ var (
_ provider.CustomStreamer = (*Provider)(nil)
_ provider.TrackPager = (*Provider)(nil)
_ provider.CodeAuthenticator = (*Provider)(nil)
_ provider.ChatCommander = (*Provider)(nil)
)

const (
Expand Down Expand Up @@ -77,6 +78,7 @@ type Provider struct {
cfg config.TelegramConfig
client *tgclient.Client
api *tg.Client
write writeAPI // tests inject a fake; production uses api
authReq chan authRequest
mu sync.Mutex // guards state and connectErr
state provState
Expand Down Expand Up @@ -259,7 +261,19 @@ func (p *Provider) currentState() provState {
// wait returns once the connection is usable. playlist.ErrNeedsAuth means the
// pane must collect the login code; other errors keep the call retryable.
func (p *Provider) wait() error {
return p.waitContext(context.Background())
}

// waitContext is wait with a caller that can give up. The provider can spend
// up to connectWait settling, and a canceled UI action should not stay blocked
// in the polling loop until that deadline.
func (p *Provider) waitContext(ctx context.Context) error {
if ctx == nil {
ctx = context.Background()
}
deadline := time.Now().Add(connectWait)
ticker := time.NewTicker(100 * time.Millisecond)
defer ticker.Stop()
for {
switch p.currentState() {
case provReady:
Expand All @@ -275,7 +289,11 @@ func (p *Provider) wait() error {
if time.Now().After(deadline) {
return errors.New("telegram: still connecting, try again")
}
time.Sleep(100 * time.Millisecond)
select {
case <-ctx.Done():
return ctx.Err()
case <-ticker.C:
}
}
}

Expand Down
Loading
Loading