Develop to main

.github/workflows/buildrelease.yml

@@ -3,9 +3,14 @@ name: Build and Release
 # Triggers:
 # - Release published with tags:
 #   - server-v* : Build only Server
-#   - app-v*    : Build only TFMAudioApp (Android, Windows, macOS)
-#   - v*        : Build everything
-# - Manual workflow dispatch with checkboxes
+#   - app-v*    : Build only TFMAudioApp (Android, Windows, macOS) — on demand
+#   - v*        : Build only Server (mobile apps are NOT built by default)
+# - Manual workflow dispatch with checkboxes (build any target on demand)
+#
+# NOTE: Mobile apps (Android/Windows/macOS) are intentionally NOT built for a
+# plain "v*" release. Build them on demand when they actually change, either
+# with an "app-v*" release tag or via the manual workflow_dispatch checkboxes.
+# See docs/releases.md for the full policy.
 
 on:
   release:
@@ -128,10 +133,11 @@ jobs:
   build-android:
     name: Build Android APK
     runs-on: ubuntu-latest
-    # Run if: manual with build_android OR release with app-v* or v* (but not server-v*)
+    # On demand only: manual with build_android OR release with an app-v* tag.
+    # A plain v* release does NOT build the mobile apps.
     if: |
       (github.event_name == 'workflow_dispatch' && inputs.build_android) ||
-      (github.event_name == 'release' && (startsWith(github.event.release.tag_name, 'app-v') || (startsWith(github.event.release.tag_name, 'v') && !startsWith(github.event.release.tag_name, 'server-v'))))
+      (github.event_name == 'release' && startsWith(github.event.release.tag_name, 'app-v'))
     steps:
       - name: '📄 Checkout'
         uses: actions/checkout@v4
@@ -317,10 +323,11 @@ jobs:
   build-windows:
     name: Build Windows App
     runs-on: windows-2022
-    # Run if: manual with build_windows OR release with app-v* or v* (but not server-v*)
+    # On demand only: manual with build_windows OR release with an app-v* tag.
+    # A plain v* release does NOT build the mobile apps.
     if: |
       (github.event_name == 'workflow_dispatch' && inputs.build_windows) ||
-      (github.event_name == 'release' && (startsWith(github.event.release.tag_name, 'app-v') || (startsWith(github.event.release.tag_name, 'v') && !startsWith(github.event.release.tag_name, 'server-v'))))
+      (github.event_name == 'release' && startsWith(github.event.release.tag_name, 'app-v'))
     steps:
       - name: '📄 Checkout'
         uses: actions/checkout@v4
@@ -449,10 +456,11 @@ jobs:
   build-macos:
     name: Build macOS App
     runs-on: macos-15
-    # Run if: manual with build_macos OR release with app-v* or v* (but not server-v*)
+    # On demand only: manual with build_macos OR release with an app-v* tag.
+    # A plain v* release does NOT build the mobile apps.
     if: |
       (github.event_name == 'workflow_dispatch' && inputs.build_macos) ||
-      (github.event_name == 'release' && (startsWith(github.event.release.tag_name, 'app-v') || (startsWith(github.event.release.tag_name, 'v') && !startsWith(github.event.release.tag_name, 'server-v'))))
+      (github.event_name == 'release' && startsWith(github.event.release.tag_name, 'app-v'))
     steps:
       - name: '📄 Checkout'
         uses: actions/checkout@v4

.gitignore

@@ -1,3 +1,4 @@
 TelegramDownloader/userData.json
 TelegramDownloader/.claude/
 .claude/
+plans/

README.md

@@ -100,6 +100,46 @@ services:
 - When you want, you can download the files again to a location on your local computer, selecting the files or folders and clicking the `Download to Local` button.
 
 
+## Android apps
+
+Both apps are native Kotlin + Jetpack Compose clients built on the server's REST API v1
+(`/api/v1`), documented in [`docs/api`](docs/api). Point them at your server address and
+API key and they work over the same Telegram session as the web.
+
+### Phone and tablet — [tfm-android-app](https://github.com/mateof/tfm-android-app)
+
+Full file manager on the go:
+
+- Telegram login from the app, by **QR** or phone number (with 2FA).
+- **Channels**: saved / all / favourites, search, statistics, create a channel, join by
+  invitation, leave, and build or refresh a channel index choosing which media types to
+  scan.
+- **File browser** with breadcrumbs, filters, recursive search, multi-select, folder
+  creation, rename, copy/move, delete, **upload from the device** and download to the
+  server or to the device.
+- **Server local storage**: browse, upload, send to a Telegram channel without
+  re-uploading the bytes, and clear the streaming cache.
+- **Live transfers** over the `/hubs/transfers` SignalR hub: speed, progress and queues,
+  with global and per-item pause, resume, cancel and retry.
+- **Background audio player** (Media3 + MediaSession) with a mini player and server-side
+  playlists, plus **video streaming** for channel and local files.
+- Server settings: simultaneous downloads, parallel chunks, connections per download.
+
+### Android TV and Fire TV — [tfm-android-tv-app](https://github.com/mateof/tfm-android-tv-app)
+
+A D-pad first client focused on watching the videos you keep in your channels:
+
+- Channels split into mine, shared, favourites, Telegram chat folders and all, with a
+  name search.
+- Folder navigation inside a channel, an **all videos** view and a **messages** view,
+  each sortable by name, date or size.
+- Playback with the built-in player (ExoPlayer plus FFmpeg software decoders, so MKV or
+  AVI with AC3/DTS play fine), VLC, any other installed player or the system default.
+- Updates itself from GitHub Releases, and runs on Android 6.0, which covers Fire TV
+  sticks from 2015 onwards.
+
+Both repositories publish a signed APK as a GitHub Release on every push to `main`.
+
 ## Music player
 
 <img width="598" height="889" alt="Music player" src="https://github.com/user-attachments/assets/c4842c34-ea8f-4664-b22c-93b43a9aaf02" />

TelegramDownloader/Configuration/config.example.json

@@ -5,5 +5,7 @@
   "mongo_connection_string": "",
   "avoid_checking_certificate": false,
   "open_browser_on_startup": true,
-  "mobile_api_key": "my_api_key"
+  "mobile_api_key": "my_api_key",
+  "webdav_user": "",
+  "webdav_password": ""
 }

TelegramDownloader/Controllers/Api/V1/ApiV1ControllerBase.cs

@@ -0,0 +1,61 @@
+using Microsoft.AspNetCore.Mvc;
+using TelegramDownloader.Models.Api;
+
+namespace TelegramDownloader.Controllers.Api.V1
+{
+    /// <summary>
+    /// Shared plumbing for every v1 controller: consistent envelopes, consistent
+    /// status codes and a helper to build absolute URLs behind a reverse proxy.
+    /// </summary>
+    [ApiController]
+    [Produces("application/json")]
+    [ProducesResponseType(typeof(ApiResult<object>), StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(typeof(ApiResult<object>), StatusCodes.Status500InternalServerError)]
+    public abstract class ApiV1ControllerBase : ControllerBase
+    {
+        /// <summary>
+        /// Absolute base URL of this server as seen by the client, honouring
+        /// <c>X-Forwarded-Proto</c>/<c>X-Forwarded-Host</c> (the app enables
+        /// forwarded headers at startup).
+        /// </summary>
+        protected string BaseUrl => $"{Request.Scheme}://{Request.Host}";
+
+        protected IActionResult OkResult<T>(T data, string? message = null) =>
+            Ok(ApiResult<T>.Ok(data, message));
+
+        protected IActionResult OkPaged<T>(T data, PageInfo page) =>
+            Ok(ApiResult<T>.Ok(data, page));
+
+        protected IActionResult OkEmpty(string? message = null) =>
+            Ok(ApiResult.Done(message));
+
+        protected IActionResult BadRequestResult(string message, string code = ApiErrorCodes.InvalidRequest, string? detail = null) =>
+            BadRequest(ApiResult.Fail(code, message, detail));
+
+        protected IActionResult NotFoundResult(string message, string code = ApiErrorCodes.NotFound) =>
+            NotFound(ApiResult.Fail(code, message));
+
+        protected IActionResult ConflictResult(string message, string code = ApiErrorCodes.Conflict) =>
+            Conflict(ApiResult.Fail(code, message));
+
+        protected IActionResult ForbiddenResult(string message) =>
+            StatusCode(StatusCodes.Status403Forbidden, ApiResult.Fail(ApiErrorCodes.Forbidden, message));
+
+        protected IActionResult ErrorResult(string message, Exception? ex = null, string code = ApiErrorCodes.InternalError) =>
+            StatusCode(StatusCodes.Status500InternalServerError, ApiResult.Fail(code, message, ex?.Message));
+
+        protected IActionResult UnavailableResult(string message, string code = ApiErrorCodes.ServiceUnavailable) =>
+            StatusCode(StatusCodes.Status503ServiceUnavailable, ApiResult.Fail(code, message));
+
+        /// <summary>
+        /// Applies in-memory paging to an already materialised list and returns
+        /// both the page and its metadata.
+        /// </summary>
+        protected static (List<T> Items, PageInfo Page) Paginate<T>(IReadOnlyList<T> source, PagedQuery query)
+        {
+            var page = PageInfo.Create(query.Page, query.PageSize, source.Count);
+            var items = source.Skip((query.Page - 1) * query.PageSize).Take(query.PageSize).ToList();
+            return (items, page);
+        }
+    }
+}