yavsc/INSTALL.md
Paul Schneider 7cda466fa8
feat(postit): add native PayPal subscription page
Add bearer-authenticated subscription checkout, reconciliation and cancellation on the authority host, reuse web subscription services, and document the flow with regression tests.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-10 23:57:26 +00:00

659 lines
35 KiB
Markdown

# Install
With internet access, Git, dotnet, Node.js, and GNU/Makefile, simply follow these instructions, in order to have the server part installed:
```bash
git clone https://github.com/pschneider/yavsc.git
cd yavsc
dotnet restore
npm install # restore front-end dependencies
npm run build:js # build the JS/CSS bundles into wwwroot
cd contrib
make install
```
The front-end bundles (under `src/Yavsc.Org/wwwroot/js/*.bundle.min.js`
and `src/Yavsc.Org/wwwroot/css/*.min.css`) are produced by `npm run
build:js` and committed to the repo, so the runtime .NET stack does
not need a Node toolchain at publish time. Re-run `npm run build:js`
after editing any of the entry files under `src/Yavsc.Org/wwwroot/js/`
or any of the `build/*.entry.js` bundle manifests.
About the mobile app,
```bash
cd src/PostIt/PostIt.Android
dotnet publish -c Release
```
and then, install the app, from the `src/PostIt/PostIt.Android/bin/Release/net10.0/PostIt.apk`
## PostIt.Desktop on Windows (per-user installer)
Build prerequisites: the .NET 10 SDK and NSIS 3 (with its standard
Modern UI 2 includes). From the repository root, publish a self-contained
Windows x64 application, then package the **entire** publish directory:
```powershell
dotnet publish src/PostIt/PostIt.Desktop/PostIt.Desktop.csproj -c Release -r win-x64 --self-contained true -p:PublishSingleFile=false
makensis /DAPP_VERSION=1.1.0-estimate.1 contrib/Windows/postit.nsi
```
Set `APP_VERSION` to the version of the published application (the
`Version` property in `PostIt.Desktop.csproj`). NSIS requires this value;
it is used in the installer filename and Windows' installed-apps list.
On Linux, use `makensis -DAPP_VERSION=1.1.0-estimate.1 contrib/Windows/postit.nsi`
instead. Cross-publishing uses the same `dotnet publish` command.
If `makensis` is not on `PATH` on Windows, invoke the executable from
the NSIS installation directory.
The result is `contrib/Windows/PostIt-<version>-win-x64-Setup.exe`.
NSIS also accepts `PUBLISH_DIR` (an absolute path to a different
**win-x64** publish directory) and `OUTPUT_FILE` (the output executable
path), with the same `/DNAME=value` or `-DNAME=value` syntax. Quote an
entire define argument when its value contains spaces.
The installer does not request elevation or install a shared .NET runtime.
It installs in `%LOCALAPPDATA%\Yavsc\PostIt.Desktop`, creates a Start menu
shortcut for the current user and registers `postit://` in
`HKCU\Software\Classes` so browser-based sign-in returns to PostIt.
Windows' installed-apps list provides the uninstaller. Close PostIt before
installing an update or uninstalling it.
The `app` subdirectory is reserved for published application files and is
removed recursively on uninstall. User settings and tokens stored outside
this directory are preserved. Reinstalling uses the recorded installation
directory and overwrites the packaged files.
The self-contained publication includes .NET, but does **not** add native
LibVLC libraries: video playback still requires a compatible Windows x64
LibVLC installation. PostIt reports an unavailable video player and offers
the system browser as an alternative.
Before distributing a release, test installation, startup, the `postit://`
login callback, updating and uninstallation on Windows with a standard
(non-administrator) account. Installer compilation alone does not validate
these Windows runtime behaviours.
## Resource consumption and CGU
### Account withdrawal and payment retention
Apply the `AccountWithdrawal` migration before deploying all three hosts. It adds
withdrawal timestamps and replaces the immutable alternate email key with a
required unique email index, preserving uniqueness while allowing pseudonymization.
Do not run the withdrawal flow until every host uses the matching backend.
Yavsc.Org must have write/delete access to the same managed volumes as API/Blogs:
`Site:UserFilesRoot`, `Site:Avatars` and `Podcast:RootPath`.
Use absolute paths shared across processes; defaults relative to application
directories are not shared automatically. Accounting files under `Site:Bills`
are not erased by withdrawal. Symbolic links in managed user directories are
refused rather than followed.
The account is blocked before cancellation/erasure, and withdrawal is only
confirmed when these operations and pseudonymization succeed. On an explicit
failure, an administrator must fix the cause and retry the existing administrative
withdrawal action. Ensure no live upload/encoding operation is still writing to
the user's volumes during withdrawal; drain such operations before retrying.
The Org hosted worker purges eligible technical payment records at startup and
checks at most every minute, with an earlier wake-up for a known anniversary.
Monitor errors and service availability: scheduled processing
cannot ensure an exact wall-clock deletion while the host is stopped. At least
one Org instance must run, and an external operations process must enforce the
one-year retention deadline during prolonged downtime. PostIt administrators can
also confirm and run `POST /api/v1/administration/payment-residues/purge`.
The report counts accounts, subscriptions, monthly payments, donations and legacy
PayPal payments. Active accounts and unfinished withdrawals are never purged.
No new subscription credits may be granted after withdrawal begins.
Invoice payments, invoices and other legal accounting records are excluded.
Define and publish the actual accounting, logs and backup retention policy for
the deployment, verify configured providers and international-transfer safeguards,
and prevent withdrawn data from being reactivated by backup restoration.
Configure the **same** `ResourceUsage` section on Yavsc.Api, Yavsc.Blogs and
Yavsc.Org. API and Blogs must also use the same application database.
All three hosts and configuration templates inherit the backend defaults
from [ResourceUsageOptions](src/Yavsc.Server/Settings/ResourceUsageOptions.cs).
Deploy matching backend versions across hosts. The public CGU renders the
effective coefficients and limit. The default limit is 1,000 points.
The following is an example explicit override, not a duplicate of defaults.
Use the account's immutable user ID (`sub`), not its login, for overrides:
```json
{
"ResourceUsage": {
"ApiCallWeight": 0.2,
"CpuSecondWeight": 0.1,
"BandwidthMbWeight": 0.05,
"StorageMbWeight": 0.5,
"DefaultLimit": 1000,
"UserLimits": {
"example-account-id": 20000
}
}
}
```
Environment variables follow ASP.NET's convention, for example
`ResourceUsage__DefaultLimit` and
`ResourceUsage__UserLimits__example-account-id`. Restart all three services
after changing the rule. Invalid weights or limits fail startup.
Existing cumulative `ResourceUsageRecords` are reused, and changing weights
recalculates their gross indicator. Apply the `ResourceSubscriptions`
migration before deploying any of the three hosts: it adds the credit
balance and subscription/payment tables without clearing existing counters.
Consumption is in **points**, independent of `EstimatedCompensation` and
currency. Counters have no automatic reset. Storage means cumulative
instrumented writes less individually tracked bytes removed or replaced,
not total filesystem occupancy. Replacements refund their tracked previous
size and charge the new size. Legacy files without an individual receipt
receive no refund; storage counters never become negative. Deletion remains
available at the consumption limit, but API/transfer/CPU costs are not refunded.
Apply the `RefundableResourceStorage` migration before deployment; its empty
receipt table deliberately does not infer provenance from historical counters.
Renames preserve receipts and repeated PDF generation replaces the previous
tracked volume rather than charging the whole file again. The historical CPU counter is
instrumented elapsed processing time, not exhaustive CPU profiling.
Authenticated HTTP operations are admitted atomically against known costs
(API call and declared request body). Personal-file uploads additionally
check their aggregate storage cost before writing. Response bytes and
unknown-length request bodies are measured through counting streams, and
remaining costs are recorded after execution, including failed requests.
PostgreSQL transaction-scoped advisory locks serialize admission and
accounting for each user across hosts. In-flight operations can exceed the
limit through costs unknown at admission; subsequent operations return
HTTP 429 with `resource_quota_exceeded` Problem Details. No permanent account
suspension or strict running-operation interruption is performed.
`GET /api/v1/resource-usage/me` returns `Consumption`, `ConsumptionLimit`,
`RemainingConsumption` and `IsQuotaReached`, alongside existing counters.
It also returns `GrossConsumption`, `AppliedCredits` and `CreditBalance`.
`Consumption` is the gross indicator less acquired credits, floored at zero.
`RemainingConsumption` includes both unused free quota and carried credit.
Usage consultation (including the role-protected admin overview), login,
session refresh and the CGU remain accessible without consuming quota.
The quota does not measure local PostIt resources, direct peer calls or
WebSocket traffic. HTTP upload size limits and disk quotas still apply.
The public page `/Home/CGU` describes the effective rule and default limit
(and the individual limit for a signed-in user). It is linked from the Web
footer and PostIt's **About** page, using the configured authentication
authority. PostIt displays consumption and remaining points in **My profile**
and the administration usage views.
### Monthly resource subscriptions (PayPal REST)
The free registration keeps the configured cumulative quota without a
monthly reset. Discovery costs EUR 1 excluding VAT (EUR 1.20 including 20%
VAT) per month; Premium costs EUR 2 excluding VAT (EUR 2.40 including VAT).
Every **confirmed payment** grants up to one / three default quotas,
respectively, with renewal on the UTC monthly anniversary of the PayPal
start date. The pack allowance is captured at subscription creation, not
multiplied by an individual user's quota override.
At reconciliation, old carried credit is used first; the new allowance
erases remaining net usage. Two thirds of the unused allowance are added
to permanent carried credit, rounded down to eight decimal places.
Old carried credit never loses another third and survives cancellation.
Example: 400 points of usage and 1,000 new points erase 400 and carry
400; an idle Premium month carries 2,000 points.
Counters are never deleted. Pending/failed payments give no credit.
Refunds (including partial refunds) revoke the corresponding award once.
Discovery grants **twice `Constants.DefaultFSQ`** (1,000 MiB), and Premium
**five times `Constants.DefaultFSQ`** (2,500 MiB) of disk space during each
confirmed, non-reversed paid monthly period. Free registrations use the standard quota.
The reference is the standard free quota (500 MiB), not an individual's
administratively adjusted `DiskQuota`. That base quota is never overwritten.
New user objects now use the existing 500 MiB database default rather than
the former 512 MiB CLR initializer; existing accounts retain their stored quota.
Cancellation retains the disk allowance through the UTC anniversary ending
the paid period; expiry or refund restores the base quota without deleting
existing files. Uploads exceeding available space are refused before writing.
The maximum size of one file and separate podcast limits are unchanged.
Pending/failed payments grant no disk bonus. Apply the
`ResourceSubscriptions`, `PremiumDiskQuota` and `DiscoveryDiskQuota` EF migrations to the shared
database before deploying any host. Profile and usage responses expose the
effective disk quota; usage also exposes `PremiumDiskQuotaUntil` and `DiscoveryDiskQuotaUntil`.
When paid periods overlap, Premium takes precedence until its expiry, then
any still-paid Discovery period applies.
Configure only **Yavsc.Org** for PayPal subscriptions. API and Blogs need
the migrated shared database and matching resource weights, not PayPal
credentials. Existing Classic donation settings remain unchanged.
PostIt's **Mon abonnement PayPal** page (Home, profile or About) loads offers
and creates/resumes checkout through `api/v1/resource-subscriptions` on the
configured OIDC **authority**, not the business API host. These routes require
the current bearer token, reject cookie-only requests, and remain accessible
at the resource-consumption limit. Prices, VAT, monthly points and plan IDs
are controlled by the server; no PayPal credentials are shipped to PostIt.
Only approval opens in the browser. The anonymous `/api/v1/resource-subscriptions/return`
landing page asks the user to return to PostIt and press **Actualiser**:
it does not reconcile or grant credit, and requires no second web login.
The authenticated `POST refresh` reconciles verified PayPal transactions;
`POST {id}/cancel` cancels only the caller's subscription. Existing web
checkout and verified webhooks remain supported. Deploy Yavsc.Org with the
new routes before distributing the updated client. Example requests are in
[`resource-subscriptions.http`](src/Yavsc.Org/resource-subscriptions.http).
Use the existing `PayPal:Mode`, `PayPal:ClientId` and `PayPal:ClientSecret`
REST settings; keep credentials in user-secrets or environment variables.
```json
{
"ResourceSubscriptions": {
"DiscoveryPlanId": "P-REPLACEWITHDISCOVERYPLAN",
"PremiumPlanId": "P-REPLACEWITHPREMIUMPLAN",
"WebhookId": "REPLACEWITHWEBHOOKID",
"DiscoveryPriceExcludingTax": 1,
"PremiumPriceExcludingTax": 2,
"VatPercent": 20
}
}
```
Before enabling checkout, create a PayPal subscription product and two
**ACTIVE** billing plans in the same REST app and environment:
one indefinite `REGULAR` cycle with `interval_unit: MONTH`,
`interval_count: 1`, `total_cycles: 0`, and EUR `fixed_price.value`
of **1.20** / **2.40** respectively. These are **already VAT-inclusive**
amounts: do not add PayPal tax, setup fees, trials, quantity support or
shipping fees. Disable billing outstanding balances in the plans
(`auto_bill_outstanding: false`) to avoid bundling missed installments
into an amount that does not match one monthly payment.
Checkout checks the configured plan against its expected TTC amount and
refuses automatic collection of outstanding balances.
Numerically invalid pricing fails startup; missing plan IDs/webhook/
credentials returns an explicit unavailable error instead of a fake success.
Register the HTTPS endpoint
`https://<Yavsc.Org host>/ResourceSubscription/Notify` in that REST app.
Subscribe to `BILLING.SUBSCRIPTION.ACTIVATED`, `UPDATED`, `CANCELLED`,
`SUSPENDED`, `EXPIRED`, `PAYMENT.FAILED`, and `PAYMENT.SALE.COMPLETED`,
`REFUNDED`, `REVERSED` (the lifecycle events use the
`BILLING.SUBSCRIPTION.` prefix). Set the returned webhook ID in configuration.
The server verifies the signature through PayPal, then fetches the bound
subscription and transaction history; it never grants credit from an
unverified webhook or the browser return. Payment IDs and monthly cycles
are unique, and the same per-user PostgreSQL lock serializes usage and awards.
Delayed notifications take effect on the usage measured when reconciled.
Users manage subscriptions at `/ResourceSubscription`, linked from the Web
footer and PostIt's About/profile pages. A browser Web login may be required
independently of PostIt's session. Create/refresh/cancel require antiforgery
tokens and ownership; the management page remains available at the quota.
**Refresh payments** reconciles missed notifications and historical refunds.
Cancellation is confirmed with PayPal, not merely recorded locally.
Only one non-terminal subscription is allowed per account.
An uncertain creation is retried with its same PayPal request ID for at
most 24 hours; an older unresolved creation requires merchant-side review
before allowing a second checkout. Do not delete that record and retry
without checking PayPal for a possible existing agreement.
Run a real Sandbox approval, first payment, renewal, repeated webhook,
refund and cancellation before enabling production. The repository tests
use synthetic PayPal transports and do not validate merchant credentials
or PayPal account eligibility.
## Podcast live broadcasts and replays
### OBS Studio for planned emissions
OBS publishes **encrypted SRT directly to Yavsc.Api**, using
[FFmpeg.NET](https://github.com/cmxl/FFmpeg.NET) (`xFFmpeg.NET`) to manage FFmpeg
listeners. No MediaMTX, external media server, authentication callback or RTMPS
certificate is required. Install **FFmpeg with libsrt, H.264/AAC and MPEG-TS
support** on the **single Yavsc.Api media host** (`ffmpeg -h protocol=srt`).
OBS supports SRT in its Custom streaming service; see its
[SRT streaming guide](https://obsproject.com/kb/srt-protocol-streaming-guide).
This replaces the previous RTMP/RTMPS transport, not the authenticated playback API.
Apply the `PodcastObsIngestion` migration on the shared database. Configure
`Podcast:Obs` on **Yavsc.Api only**, for example:
```json
{
"Podcast": {
"Obs": {
"Enabled": true,
"ServerUrl": "srt://obs.example.org",
"ListenAddress": "0.0.0.0",
"FirstPort": 10000,
"PortCount": 16,
"ActivationMinutes": 30,
"MaxDurationMinutes": 120,
"MaxConcurrentBroadcasts": 2
}
}
}
```
`ServerUrl` contains the public SRT host only, with no port, path, secret or query.
`ListenAddress` is a literal local IP address (IPv4 or IPv6); configure a matching
public address family. Open/forward **UDP 10000-10015** in this example.
An ordinary HTTP reverse proxy does not carry SRT. NAT forwarding must preserve
the advertised port numbers.
One FFmpeg process and UDP port are reserved per armed emission, even before OBS
connects. Armed and running emissions share `MaxConcurrentBroadcasts`; an exhausted
pool returns HTTP 503. The port range is bounded (at most 128 ports) and must be
large enough for the concurrency limit. Listener startup failure is reported,
not treated as successful activation.
Keep process arguments and credentials accessible only to the service administrator.
Limit ingress bitrate at the network level and in OBS: application quotas are checked
on completed media segments, not on every incoming packet.
In PostIt:
1. Prepare an emission and select it.
2. Choose **Activer OBS / renouveler la cle**.
3. In OBS, select **Parametres > Stream > Service : Personnalise**, then copy
the complete displayed **secret SRT URL as Server**, leaving **Stream Key empty**.
The URL includes caller mode, a random passphrase and enforced AES-256 encryption.
Use **H.264 video**, **AAC audio**,
a **2-second keyframe interval** and a bitrate producing segments below 8 MiB.
4. Start streaming in OBS before the activation expires. The actual emission
starts when the first complete media segment arrives, even if the scheduled date is later.
No camera capture in PostIt is required; PostIt may be closed afterwards.
5. Stop OBS or choose **Revoquer OBS et arreter le diffuseur** in PostIt.
Committed segments remain available and the normal MP4 worker prepares replay.
Passphrases are scoped to one emission, displayed once and rotated on activation.
Only a SHA-256 hash and lifecycle metadata are stored in the database; FFmpeg needs
the actual passphrase in memory/process arguments for SRT encryption. It is never
included in status responses or persisted in PostIt. Navigation/logout clears
the displayed secret URL but does not revoke a running
external emission. Revocation is available at the consumption limit.
After disconnect, restart or timeout, the emission ends rather than silently
resuming under a new publisher: prepare a new emission for another broadcast.
An API restart invalidates all old activations; an unstarted emission must be
activated again because its passphrase is not recoverable from the database.
An invalid handshake can end an armed listener; no podcast is created without
media, and the owner can activate again. Rate-limit connection attempts at deployment.
The worker manages bounded FFmpeg.NET listener/remuxing tasks. It rejects ended,
deleted, revoked or withdrawn accounts and caps
concurrent captures and duration (the lower of planned duration and configured
maximum). Revocation cancels the corresponding FFmpeg process and frees its port.
Activation expiry stops unused listeners. The passphrase is required before SRT
media can be received; a stream name alone is not an authentication mechanism.
Committed segments are charged as transferred and stored MiB under the same
consumption rule; their storage receipts are refunded on podcast deletion.
OBS storage counts towards the user's effective disk quota and the existing
podcast media limits. Pending capture files are monitored and bounded; enforcement
can overshoot by one polling interval of incoming data. Processing errors are
reported in the owner-only OBS status endpoint, without exposing secret URLs or
FFmpeg diagnostics. Monitor process/cleanup failures and drain active captures
before maintenance. An API outage ends ingestion and requires reactivation.
The normal HTTP API authenticates playback; OBS stream credentials never grant
viewer or account access.
For the real media regressions, install FFmpeg with libsrt and run:
```bash
dotnet test --project src/test/Yavsc.Api.Tests/Yavsc.Api.Tests.csproj --filter-class '*PodcastObsTests'
```
The tests launch loopback-only listeners, generate synthetic H.264/AAC media
with FFmpeg, verify encrypted SRT through FFmpeg.NET, wrong-passphrase rejection,
revocation during streaming,
AAC audio, HLS segments, MP4 replay and refund,
then stops its own processes and removes its temporary files.
PostIt Desktop's home page provides **Podcasts : directs et replays**.
Install LibVLC 3 with the `livehttp`, MPEG-TS, x264 and AAC plugins on the
Desktop machine. Windows capture uses DirectShow; Linux uses V4L2 and the
default PulseAudio microphone. FFmpeg is **not** a client dependency.
Select a camera and optionally a microphone, enter a title, then start.
An **Apercu local de la capture** appears at the top of the Podcasts page on
Android and Desktop. It uses the current capture, not a second camera session
or the server replay. Android displays the same oriented frames as the encoder,
with black bars to preserve proportions; Desktop duplicates LibVLC's video
output. Local microphone playback is disabled to avoid acoustic feedback.
Stopping releases the preview; hiding/recreating the Android preview surface
does not restart the encoder or change its timestamps.
Stopping publishes the retained replay; navigating away or logging out
stops capture too. A second signed-in PostIt instance can watch the live
broadcast while it is being captured.
Both upload and playback require a bearer token with the `api` scope.
All authenticated API users can watch the catalogue, live broadcasts and
replays; only the broadcaster can upload, complete or delete their podcast.
Media is not anonymous and no access token is included in a playback URL.
Configure Yavsc.Api's `Podcast` section (or environment variables such as
`Podcast__RootPath`). The base media store needs no database migration;
planned emissions and OBS require their migrations documented above. Install **FFmpeg 5+
on the API server** (with `concatf`, MPEG-TS, MP4 and AAC bitstream-filter
support; for Debian/Ubuntu: `apt-get install ffmpeg`). The API runtime stage
in the main Dockerfile includes it. Only stream-copy remuxing is performed,
not video/audio re-encoding:
```json
{
"Podcast": {
"RootPath": "/srv/yavsc-private/podcasts",
"MaxSegmentBytes": 8388608,
"MaxOwnerBytes": 1073741824,
"MaxSegments": 7200,
"MaxOwnerPodcasts": 100,
"IdleTimeoutSeconds": 60,
"FfmpegPath": "ffmpeg",
"ReplayTimeoutSeconds": 600
}
}
```
`RootPath` must be absolute, writable by Yavsc.Api and **outside any static
file directory**. The default is `DataDir/podcasts` under the API application
base directory. Use a persistent volume and back up this entire directory
(indexes and segments together). This implementation supports **one API
process per storage root**, not multiple writers or replicas.
Defaults allow 8 MiB per segment (also the HTTP endpoint's hard limit),
1 GiB retained per owner, 7,200 segments per episode and 100 episodes per
owner. At the target two-second segment duration, this is roughly four hours
per episode; the byte quota can be reached earlier. Podcast quotas are
separate from the legacy user-files `DiskQuota` for native HTTP capture.
OBS source segments also count towards the user's effective disk quota and
instrumented consumption; the additional MP4 is counted only by `MaxOwnerBytes`.
Deleting an ended podcast
releases its podcast quota. Reverse proxies must allow an 8 MiB PUT body
and forward Authorization, Range and Content-Range on every API request/response.
The retained MPEG-TS **and** the additional MP4 count toward `MaxOwnerBytes`.
Allow enough free quota and disk space for both copies and the temporary MP4;
deletion removes all copies.
A broadcast without a new committed segment for 60 seconds, or present
when the API restarts, becomes an interrupted replay on the next catalogue,
manifest or upload request. Already committed media remains playable.
The broadcaster retries transient upload errors twice using the same
sequence and content; it stops if capture fails or the pending local media
exceeds 64 MiB. Unacknowledged media is retained under
`%LOCALAPPDATA%\PostIt\podcast-capture` (Linux: the corresponding local
application data directory), with `podcast.json` and the capture playlist
for manual recovery. There is no automatic resumption after an application
restart; these private local recordings may be removed manually when no
longer needed.
On completion, the API queues a private, seekable **MP4** (`-c copy`,
`+faststart`). The persisted `replay.state` moves through `Pending`,
`Processing`, `Ready` or `Failed`; completion itself does not wait for FFmpeg.
The single API worker also queues older Completed indexes automatically,
recovers interrupted preparation after a restart, and scans every five seconds.
Interrupted broadcasts keep MPEG-TS playback unless the owner explicitly
completes them. Source segments and existing HLS routes remain available.
Preparation failure keeps all source media and reports an error; after checking
server logs, FFmpeg installation, timeout and quota, the owner can use PostIt's
**Relancer la preparation MP4** action, or `POST /api/v1/podcasts/{id}/replay/retry`.
The MP4 is exposed only when ready, at authenticated
`GET /api/v1/podcasts/{id}/replay.mp4` (also HEAD; byte ranges supported).
PostIt's Android and Desktop player waits for MP4 preparation, then fetches
bounded authenticated ranges with token refresh rather than giving LibVLC
a bearer URL. Replay controls overlay the native video: play/pause, position,
duration and draggable seek bar. They hide after three seconds without
interaction while playing, stay visible during seeking/pause/keyboard focus,
and reappear on pointer movement or touch.
The live player still joins up to three segments behind the edge. Native
camera/microphone permissions, drivers and codecs must still be verified
on each target Windows/Linux machine.
### Android podcasts
The Android APK bundles LibVLC and uses a native Android video surface inside
the same Avalonia video page as desktop. Catalogue, playback controls and
authenticated segment downloads are shared; no external browser, public media
URL or camera/microphone permissions are needed to watch a podcast.
Video playback keeps the screen awake while PostIt is visible. Pausing,
stopping, reaching the end, a playback error or leaving the video releases
this request; backgrounding the app always allows the screen to sleep.
The podcast page offers **Garder l'ecran allume pendant l'apercu camera et le
direct** on Android. This preference is saved and disabled by default. It
only keeps the screen awake during an active camera preview or broadcast
while PostIt is visible, and can be changed during capture. Turning it off
does not stop capture or alter the existing background broadcast service.
Leaving the app stops playback and cancels downloads. Returning recreates the
player: a replay starts from the beginning, and a live stream rejoins near the
live edge. Seeking and background audio are not supported.
Broadcasting requires **Android 8 (API 26) or newer**. In the shared podcast
page, detect devices, select front/rear camera and optionally the microphone,
then start the live broadcast while PostIt is visible. Camera permission,
microphone permission when selected, and notification permission on Android 13+
must be granted. A permission denial is reported in the page without starting
capture or creating a server broadcast. Permissions are requested before the
server session is created so a long permission dialog cannot expire it.
Watching does not request these permissions.
Android uses Camera2 and its native MediaRecorder H.264/AAC encoder, up to 480p at 30 fps,
not the desktop LibVLC camera inputs or software encoders. MPEG-TS is segmented
at IDR frames, with timestamps used for segment durations. Closed segments
enter the same ordered upload/retry/quota/replay pipeline as desktop.
Devices without a supported camera/encoder report a startup error.
On Android, the optional **Flouter le decor de la camera** setting is saved
locally and disabled by default. It applies to podcast camera preview and
recording, not calls or OBS. The bundled Apache-2.0 PPHumanSeg model from
[OpenCV Zoo](https://github.com/opencv/opencv_zoo/tree/main/models/human_segmentation_pphumanseg)
is evaluated locally with ONNX Runtime; OpenGL blends the blurred background
before the native encoder. No frames are sent to a third party. Segmentation
is imperfect and can expose parts of the background: check the preview and do
not rely on it to conceal sensitive surroundings. Performance and battery
usage depend on the device. Capture stops on processing failure.
The bundled `pphumanseg.onnx` is the OpenCV Zoo 2023mar model (SHA-256
`552d8a984054e59b5d773d24b9b12022b22046ceb2bbc4c9aaeaceb36a9ddf24`);
its Apache-2.0 license is included beside the asset.
ONNX Runtime's Android library requires API 24; it is only loaded by the
podcast capture code, which is restricted to API 26 and later. The manifest
override preserves PostIt's existing API 23 minimum for its other features.
Camera frames are rotated through an OpenGL surface before encoding, so both
live playback and replays have upright pixels without relying on rotation
metadata (not supported by the MPEG-TS recorder). The sensor, front/rear lens
and display orientation are sampled when capture starts; portrait output swaps
width and height. Camera2 may already include sensor rotation in the
SurfaceTexture transform; only the remaining rotation is applied by OpenGL.
Keep that device orientation during a broadcast, or stop and
start a new broadcast after turning the device.
A camera/microphone foreground service and a partial wake lock maintain the
broadcast when PostIt is backgrounded or the screen locks. Its ongoing
notification returns to the app and offers **Arreter et publier**. Stopping
flushes the final segment before completing the replay. Leaving the podcast
page or logging out still stops capture. Android's explicit service stop,
process termination or application restart does not automatically restart a
camera; segments already received by the server remain available under the
interrupted-replay rules above. Device power policies can impose additional
restrictions and must be tested on the intended physical devices.
**Native library compatibility:** the Android app now uses
`VideoLAN.LibVLC.Android` 3.7.0-beta, which is the minimum compatible package
for 16 KiB-page devices. Older 3.6.5 binaries can fail at runtime with
`failed to load libc++_shared.so` or the linker error `XA0141` because the
native libraries are not aligned for 16 KiB memory pages. A successful APK
build or a test on a 4 KiB-page emulator does not establish compatibility
for 16 KiB-page devices or Play distribution requiring that alignment.
Build with the Android workload and SDK configured:
```bash
dotnet build src/PostIt/PostIt.Android/PostIt.Android.csproj
```
On an Android device, verify replay video/audio, live playback, pause/resume,
rotation, Back navigation and returning after backgrounding the app. Also
verify an expired session or interrupted network reports a playback error.
For broadcasting, test front/rear cameras, microphone enabled/disabled,
permission denial, screen lock, background capture, notification stop and the
final replay. No automatic retry of a denied permission or a killed camera
service is performed.
The Debug APK includes a local native-capture test activity (excluded from
Release); it does not create a server podcast. On a dedicated emulator, grant
camera, audio and notification permissions, then run:
```bash
adb shell am start -W -f 0x18000000 -n fr.pschneider.postit/fr.pschneider.postit.PodcastCaptureTestActivity
# Wait about 20 seconds for foreground/background recording and final flush.
adb shell run-as fr.pschneider.postit cat files/podcast-capture-test-result.txt
# Repeat with the second camera, no audio, and the notification stop action:
adb shell am start -W -f 0x18000000 -n fr.pschneider.postit/fr.pschneider.postit.PodcastCaptureTestActivity --es microphone false --es camera front --es notificationStop true
```
The result reports the segment count, the background progress and the private
recording directory under `files/podcast-capture-tests`. Recordings remain
there for local decoder inspection and can be removed after the test.
The implementation was checked on an Android 16 x64 emulator with 4 KiB
pages: camera/microphone capture produced five independently decodable
H.264/AAC segments across foreground/background operation; the second camera
without audio produced six decodable H.264 segments, including screen-off
operation and stop through the notification action. The foreground service
was gone after both tests. These local tests do not replace an authenticated
Android-to-server broadcast/replay test or validation on physical devices.
## Resources
System resources needed to install.
### Some TCP/IP ports to listen
The following provided services need all a port to listen :
* Org
* Blogs
* Api (to become obsolete, in favor of Performer + Client + Com + Moderation )
### A Software bloc name
In this doc, let's say, `Yavsc`
### A domain name
Wait ... `pschneider.fr`
You'll have to see with your provider, in order to power it, and make it point to your host ip, at least concerning the ports 80 & 443.
### A Postgresql db
The database must be created, and we need its connection string, allowed to modify the data dictionary, see the `.env` file
### An Smtp mail service
You'll need to send e-mail ... using smtp and the provider of your choice, see the `.env` file.
### Google
I'll have to make with it, a least a moment, it needs a *service account*, and some setup,
in the `appsettings.*.json` file, and
the execution environment variable GOOGLE_APPLICATION_CREDENTIALS to a value pointing the json description file for the Google Service account.