Merge pull request #556 from michaelmoskie/issue/477-client-playlists

Add playlist editing endpoints for connected clients

Author: henriquesebastiao

docs/api-reference.md

@@ -3540,6 +3540,56 @@ The playlists [`GET /playlists`](#get-playlists) lists, with track ids in playli
 
 Keep the other people's playlists apart from the caller's own (a "Shared with me" and a "Public playlists" section, each entry labelled with its `owner`).
 
+### Mobile playlist writes
+
+`GET /api/server/info` advertises `capabilities.playlist_editing: true` when these routes are available. These routes use stable mobile **track IDs**, and write only **manual** (Library-created) playlists. An inaccessible playlist or track returns `404`; imported playlists and callers without the required write permission return `403`; malformed bodies or fields return `400`; a stale reorder returns `409` without changing the playlist. The library sync index must be ready; otherwise a write returns `503` (`Starting up`). There is no whole-playlist delete route in this mobile API.
+
+Create and rename require the playlist owner or an admin. Add, remove, and reorder require the owner, an admin, or an editor of a shared playlist. Successful changes notify connected WebSocket clients with `playlists_changed` according to playlist visibility.
+
+All successful writes return the canonical shape `{ "name", "manual", "count", "track_ids" }`, where `track_ids` is in playlist order and includes every repeated occurrence. Rename also returns `previous`; track edits may also return `added`, `removed`, and `already`.
+
+#### `POST /api/v1/playlists`
+
+Create an empty manual playlist.
+
+**Body:** `{ "name": "Late night" }`
+
+**Response:** `{ "name": "Late night", "manual": true, "count": 0, "track_ids": [] }`
+
+#### `POST /api/v1/playlists/rename`
+
+Rename a manual playlist.
+
+**Body:** `{ "name": "Late night", "new_name": "Night drive" }`
+
+**Response:** `{ "name": "Night drive", "previous": "Late night", "manual": true, "count": 0, "track_ids": [] }`
+
+#### `POST /api/v1/playlists/tracks`
+
+Add or remove tracks from a manual playlist. The body accepts `name` and any combination of these optional fields:
+
+```json
+{
+  "name": "Late night",
+  "add": ["track-id"],
+  "remove": ["track-id"],
+  "remove_entries": [{ "track_id": "track-id", "occurrence": 0 }],
+  "allow_duplicates": false
+}
+```
+
+`add` and `remove` are arrays of track IDs. `remove` removes every copy of each ID; `remove_entries` removes only the specified zero-based occurrence of an ID in playlist order. A missing occurrence removes nothing. By default, adding an ID already in the playlist skips it and lists it in `already`; set `allow_duplicates` to `true` to add another copy. The response may include `added` and `removed` counts and `already` track IDs, alongside the canonical result shape.
+
+The combined number of IDs in `add`, `remove`, and `remove_entries` may not exceed 10,000. The reorder endpoint also accepts at most 10,000 IDs. Larger requests return `400` before any IDs are resolved or the playlist is changed. Unknown and caller-hidden IDs both return `404`.
+
+#### `PUT /api/v1/playlists/order`
+
+Replace the order of a manual playlist's tracks. `track_ids` must describe the caller-visible playlist contents, including each repeated occurrence.
+
+**Body:** `{ "name": "Late night", "track_ids": ["track-id", "track-id-2"] }`
+
+If the playlist changed since the client loaded it, the request returns `409`; reload and retry with the current IDs. Success returns the canonical result shape.
+
 ---
 
 ### `GET /api/v1/usernames`

docs/mobile-client-contract.md

@@ -38,7 +38,7 @@ Build the address from the resolved host + `port`. Discovery is a convenience: a
   "require_sign_in": true,
   "capabilities": {
     "transcoding": { "available": true, "formats": ["aac", "mp3", "opus"], "bitrates": [96, 128, 160, 192, 256, 320] },
-    "signed_urls": true, "pairing": true, "password_sign_in": true, "podcasts": true, "discover": true, "lyrics": true, "library_sync": true
+    "signed_urls": true, "pairing": true, "password_sign_in": true, "podcasts": true, "discover": true, "lyrics": true, "library_sync": true, "playlist_editing": true
   }
 }
 ```
@@ -152,9 +152,23 @@ Other reads, all by track id:
 | `POST /api/v1/playlists/seen` | Body `{ "name" }` — clear the `new` marker of a playlist shared with the user |
 | `GET /api/v1/playlists/hidden?name=` | `{ "name", "songs": [{ "key", "label", "track_id", "hidden_at" }] }` — the songs the user hid from an imported playlist of theirs (`track_id` is `""` once the file is gone) |
 | `POST /api/v1/playlists/hidden` | Body `{ "name", "hide": [track_ids], "show": [keys] }` — hide tracks from an imported playlist of the user's (they stay out when its watch or link brings them back; the tracks stay in the library), or show hidden ones again. Answers `{ "name", "hidden", "keys", "shown", "restored", "count", "track_ids" }`; send `keys` as `show` to undo. Offer it on `mine` playlists that aren't `manual` or `liked` (`409` otherwise). See [Hidden playlist songs](features/hidden-playlist-songs.md) |
+| `POST /api/v1/playlists` | Body `{ "name" }` — create an empty manual playlist |
+| `POST /api/v1/playlists/rename` | Body `{ "name", "new_name" }` — rename a manual playlist |
+| `POST /api/v1/playlists/tracks` | Body `{ "name", "add"?: [track_id], "remove"?: [track_id], "remove_entries"?: [{ "track_id", "occurrence" }], "allow_duplicates"?: bool }` — edit a manual playlist by track ID; at most 10,000 total references across all three arrays (`400` above the limit) |
+| `PUT /api/v1/playlists/order` | Body `{ "name", "track_ids": [...] }` — reorder a manual playlist, including repeated occurrences; at most 10,000 IDs (`400` above the limit) |
 | `GET /api/v1/likes` | `{ "track_ids": [...] }`, newest first |
 | `PUT /api/v1/likes` | Body `{ "track_id", "liked" }` — idempotent |
 
+### Editing playlists
+
+The `capabilities.playlist_editing` flag in `/api/server/info` is `true` when the server supports these writes. Use the stable track IDs from library sync, never file paths. All four routes operate on manual playlists; this API has no whole-playlist delete route. Create and rename require the owner or an admin. Adding, removing, or reordering requires the owner, an admin, or an editor of a shared playlist.
+
+Successful writes return `{ "name", "manual", "count", "track_ids" }`, with `track_ids` in playlist order and repeated once per occurrence. Rename also returns `previous`; track edits may return `added`, `removed`, and `already`.
+
+For `POST /api/v1/playlists/tracks`, `add` appends IDs; existing IDs are skipped and listed in `already` unless `allow_duplicates` is `true`. `remove` removes every copy of each ID. `remove_entries` removes only a specified zero-based `occurrence` of that ID in playlist order; a nonexistent occurrence removes nothing. For `PUT /api/v1/playlists/order`, send the current caller-visible IDs in the desired order, retaining repeated IDs. A stale list returns `409`; reload the playlist and retry.
+
+Inaccessible playlists or tracks return `404`. Imported playlists and callers without the required write permission return `403`. Invalid bodies or fields return `400`; if the library sync index is not ready, the write returns `503`. Successful playlist changes send `playlists_changed` to connected WebSocket clients according to playlist visibility.
+
 ## 5. Stream and download
 
 ```http
@@ -200,7 +214,7 @@ Messages the app can rely on:
 | Message | When |
 |---------|------|
 | `{ "type": "library_changed" }` | Tracks were added, removed or moved (debounced ~2 s) — sync |
-| `{ "type": "playlists_changed" }` | A playlist was shared, unshared, followed, copied, detached, renamed or deleted, or songs were hidden from it or shown again — refetch `GET /api/v1/playlists` |
+| `{ "type": "playlists_changed" }` | A playlist was shared, unshared, followed, copied, detached, renamed or deleted, its tracks changed, or songs were hidden from it or shown again — refetch `GET /api/v1/playlists`; playlist write notifications follow playlist visibility |
 | `{ "type": "likes", "count": 3 }` | Likes changed somewhere — refetch `GET /api/v1/likes` |
 | `{ "type": "queue_reload" }` | Many downloads were queued at once — refetch `GET /api/queue` |
 | `{ "song": {…}, "progress": 42.5, "status": "downloading"\|"done"\|"error", "message", "filename", "provider" }` | A server download's progress (no `type`) — one’s own jobs only (every job on an admin’s device) |

docs/zh-CN/mobile-client-contract.md

@@ -38,7 +38,7 @@ icon: lucide/file-code
   "require_sign_in": true,
   "capabilities": {
     "transcoding": { "available": true, "formats": ["aac", "mp3", "opus"], "bitrates": [96, 128, 160, 192, 256, 320] },
-    "signed_urls": true, "pairing": true, "password_sign_in": true, "podcasts": true, "discover": true, "lyrics": true, "library_sync": true
+    "signed_urls": true, "pairing": true, "password_sign_in": true, "podcasts": true, "discover": true, "lyrics": true, "library_sync": true, "playlist_editing": true
   }
 }
 ```
@@ -152,9 +152,23 @@ GET /api/v1/library?since=<cursor>
 | `POST /api/v1/playlists/seen` | 请求体 `{ "name" }`；清除共享给用户的播放列表上的 `new` 标记。 |
 | `GET /api/v1/playlists/hidden?name=` | `{ "name", "songs": [{ "key", "label", "track_id", "hidden_at" }] }`，即用户从自己导入的播放列表中隐藏的歌曲（文件消失后 `track_id` 为空字符串）。 |
 | `POST /api/v1/playlists/hidden` | 请求体 `{ "name", "hide": [track_ids], "show": [keys] }`；从用户导入的播放列表中隐藏曲目（监控或重新导入链接时仍保持隐藏，但曲目仍在媒体库中），或重新显示隐藏曲目。返回 `{ "name", "hidden", "keys", "shown", "restored", "count", "track_ids" }`；将 `keys` 作为 `show` 发送即可撤销隐藏。应在 `mine` 为真的、且 `manual` 和 `liked` 均为假的播放列表中提供此功能（否则返回 `409`）。参见[隐藏播放列表歌曲](features/hidden-playlist-songs.md)。 |
+| `POST /api/v1/playlists` | 请求体 `{ "name" }`；创建空的自建播放列表。 |
+| `POST /api/v1/playlists/rename` | 请求体 `{ "name", "new_name" }`；重命名自建播放列表。 |
+| `POST /api/v1/playlists/tracks` | 请求体 `{ "name", "add"?: [track_id], "remove"?: [track_id], "remove_entries"?: [{ "track_id", "occurrence" }], "allow_duplicates"?: bool }`；按曲目 ID 编辑自建播放列表；三个数组合计最多 10,000 项（超出时返回 `400`）。 |
+| `PUT /api/v1/playlists/order` | 请求体 `{ "name", "track_ids": [...] }`；调整自建播放列表的曲目顺序，包括重复项；最多 10,000 个 ID（超出时返回 `400`）。 |
 | `GET /api/v1/likes` | `{ "track_ids": [...] }`，按最新时间在前排序。 |
 | `PUT /api/v1/likes` | 请求体 `{ "track_id", "liked" }`；操作具有幂等性。 |
 
+### 编辑播放列表
+
+`/api/server/info` 中的 `capabilities.playlist_editing` 为 `true` 时，服务器支持这些写入操作。使用媒体库同步返回的稳定曲目 ID，不要使用文件路径。这四个接口仅适用于自建播放列表，不能删除整个播放列表。所有者或管理员可以重命名；所有者、管理员或共享列表的编辑者可以添加、移除和排序曲目。
+
+成功的写入返回 `{ "name", "manual", "count", "track_ids" }`，`track_ids` 按播放列表顺序排列，重复项各占一项。重命名还返回 `previous`；曲目编辑可能返回 `added`、`removed` 和 `already`。
+
+在 `POST /api/v1/playlists/tracks` 中，`add` 将曲目追加到末尾；已有曲目会被跳过并列入 `already`，除非 `allow_duplicates` 为 `true`。`remove` 移除指定曲目的所有副本；`remove_entries` 仅移除从零开始计数的指定 `occurrence`，不存在的副本不会被移除。调用 `PUT /api/v1/playlists/order` 时，按目标顺序发送当前可见的所有曲目 ID，包括重复项。列表已过期时返回 `409`；重新加载后再试。
+
+无法访问的播放列表或曲目返回 `404`；导入的播放列表或没有写入权限的调用者返回 `403`；请求体或字段无效返回 `400`；媒体库同步索引尚未就绪返回 `503`。成功修改播放列表后，服务器根据可见性向 WebSocket 客户端发送 `playlists_changed`。
+
 ## 5. 串流和下载
 
 ```http

downtify/api.py

@@ -1857,24 +1857,6 @@ def require_playlist_visible(
     return entry
 
 
-def claim_manual_playlist(name: str, request: Optional[Request]) -> None:
-    """Record a Library-created playlist's owner (best effort)."""
-
-    user_id = request_user_id(request)
-    if not user_id or state.manual_playlist_owners is None:
-        return
-    try:
-        state.manual_playlist_owners.set_owner(name, user_id)
-        if state.playlist_shares is not None:
-            # A new playlist never inherits what an older one by that name
-            # was shared with.
-            state.playlist_shares.forget(name)
-    except Exception:
-        logger.opt(exception=True).debug(
-            'Could not record owner for playlist {!r}', name
-        )
-
-
 def request_ip(request: Request) -> str:
     return client_ip(request.scope, _TRUSTED_PROXIES)
 
@@ -6995,12 +6977,18 @@ async def create_library_playlist_endpoint(request: Request) -> dict[str, Any]:
     name = str(payload.get('name') or '').strip()
     ctx = library_context()
     try:
-        result = await asyncio.to_thread(create_manual_playlist, ctx, name)
+        result = await asyncio.to_thread(
+            create_manual_playlist,
+            ctx,
+            name,
+            state.manual_playlist_owners,
+            request_user_id(request),
+            state.playlist_shares,
+        )
     except ManualPlaylistError as exc:
         raise HTTPException(
             status_code=exc.status_code, detail=str(exc)
         ) from exc
-    claim_manual_playlist(str(result.get('name') or name), request)
     invalidate_library_paths_cache()
     return result
 
@@ -7606,12 +7594,19 @@ async def copy_library_playlist_endpoint(request: Request) -> dict[str, Any]:
             new_name = f'{base} {number}'
             number += 1
     try:
-        result = await asyncio.to_thread(copy_playlist, ctx, files, new_name)
+        result = await asyncio.to_thread(
+            copy_playlist,
+            ctx,
+            files,
+            new_name,
+            state.manual_playlist_owners,
+            request_user_id(request),
+            state.playlist_shares,
+        )
     except ManualPlaylistError as exc:
         raise HTTPException(
             status_code=exc.status_code, detail=str(exc)
         ) from exc
-    claim_manual_playlist(str(result.get('name') or new_name), request)
     invalidate_library_paths_cache()
     await announce_playlists_changed()
     return result

downtify/auth_routes.py

@@ -161,6 +161,7 @@ def get_server_info() -> dict[str, Any]:
         transcoding=transcoder.capability() if transcoder else None,
     )
     result['library_only'] = api.state.settings.get('library_only') is True
+    result['capabilities']['playlist_editing'] = True
     return result
 
 

downtify/external_playlists.py

@@ -206,9 +206,14 @@ def import_snapshot(
             while name.casefold() in taken:
                 name = f'{base} ({suffix})'
                 suffix += 1
-            result = copy_playlist(ctx, files, name)
-            owners.set_owner(result['name'], user_id)
-            PlaylistShares(Path(self.path)).forget(result['name'])
+            result = copy_playlist(
+                ctx,
+                files,
+                name,
+                owners,
+                user_id,
+                PlaylistShares(Path(self.path)),
+            )
             with connect_sqlite(self.path) as conn:
                 conn.execute(
                     'INSERT INTO external_playlist_imports VALUES (?, ?, ?, ?) '

downtify/library_sync.py

@@ -33,6 +33,7 @@
 import hashlib
 import json
 import secrets
+import sqlite3
 import threading
 from collections.abc import Collection, Iterable
 from datetime import datetime, timedelta, timezone
@@ -548,6 +549,77 @@ def row_for(self, track_id: str) -> Optional[dict[str, Any]]:
             return None
         return {'id': row['track_id'], **json.loads(row['row_json'])}
 
+    def rows_for(self, track_ids: Iterable[str]) -> dict[str, dict[str, Any]]:
+        """Resolve many live ids in one database connection.
+
+        Includes the compatibility aliases handled by :meth:`row_for`.
+        Missing and deleted ids are omitted from the returned mapping.
+        """
+
+        wanted = list(dict.fromkeys(track_ids))
+        found: dict[str, dict[str, Any]] = {}
+        with self._connect() as conn:
+            for start in range(0, len(wanted), 400):
+                chunk = wanted[start : start + 400]
+                marks = ','.join('?' * len(chunk))
+                replacements: dict[str, dict[str, Any]] = {}
+                try:
+                    for row in conn.execute(
+                        f"""SELECT a.track_id, r.new_metadata
+                            FROM library_audio_sync_aliases a
+                            JOIN library_audio_replacements r
+                              ON r.old_file = a.old_file
+                            WHERE a.track_id IN ({marks})
+                              AND r.state IN ('linked','retained','removed','complete')""",
+                        chunk,
+                    ).fetchall():
+                        replacements[row['track_id']] = json.loads(
+                            row['new_metadata']
+                        )
+                except sqlite3.OperationalError as exc:
+                    # These tables are optional on installs predating audio
+                    # replacement support. Match replacement_for_id's behavior.
+                    if 'no such table' not in str(exc).lower():
+                        raise
+
+                # row_for gives compatibility aliases precedence over a
+                # same-named live id, so resolve those first.
+                replacement_paths = list({
+                    row['file'] for row in replacements.values()
+                })
+                current_rows = {}
+                if replacement_paths:
+                    marks = ','.join('?' * len(replacement_paths))
+                    current_rows = {
+                        row['path']: json.loads(row['row_json'])
+                        for row in conn.execute(
+                            f'SELECT path, row_json FROM sync_tracks '
+                            f'WHERE deleted_at IS NULL AND path IN ({marks})',
+                            replacement_paths,
+                        ).fetchall()
+                    }
+                for track_id, replacement in replacements.items():
+                    current = current_rows.get(replacement['file'])
+                    found[track_id] = (
+                        {'id': track_id, **current}
+                        if current is not None
+                        else {'id': track_id, **public_row(replacement)}
+                    )
+                remaining = [key for key in chunk if key not in replacements]
+                if not remaining:
+                    continue
+                marks = ','.join('?' * len(remaining))
+                for row in conn.execute(
+                    f'SELECT track_id, row_json FROM sync_tracks '
+                    f'WHERE deleted_at IS NULL AND track_id IN ({marks})',
+                    remaining,
+                ).fetchall():
+                    found[row['track_id']] = {
+                        'id': row['track_id'],
+                        **json.loads(row['row_json']),
+                    }
+        return found
+
     def ids_for_paths(self, paths: Iterable[str]) -> dict[str, str]:
         """``{path: track_id}`` for the paths that are known."""