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>
659 lines
35 KiB
Markdown
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.
|