From 7d8245312b0aef69e18eb4dff3dbeba34720a3b3 Mon Sep 17 00:00:00 2001
From: Adeel Ahmad
Date: Sat, 10 Oct 2026 20:02:03 +0000
Subject: [PATCH 1/3] refactor: call items assets, not recordings, unless they
are audio or video
The web app, assistant tool descriptions and replies, API descriptions,
error messages and docs now say asset (or document) for an item of any
kind. Recording stays for audio and video. API paths, MCP tool names
and stored data are unchanged.
Co-Authored-By: Claude Opus 5.5 (1M context)
Claude-Session: https://claude.ai/code/session_01RZiSmgAbLXTuQkniFKmuvr
---
.github/ISSUE_TEMPLATE/bug_report.yml | 2 +-
.github/PULL_REQUEST_TEMPLATE.md | 2 +-
CHANGELOG.md | 3 +
CONTRIBUTING.md | 2 +-
README.md | 2 +-
docs/access.md | 92 ++--
docs/activity.md | 6 +-
docs/api.md | 182 ++++----
docs/architecture.md | 10 +-
docs/assistant.md | 32 +-
docs/authentication.md | 6 +-
docs/backend-gaps.md | 8 +-
docs/components.md | 2 +-
docs/configuration.md | 4 +-
docs/contributing.md | 2 +-
docs/database.md | 4 +-
docs/encryption.md | 6 +-
docs/fedora.md | 8 +-
docs/graph-history.md | 4 +-
docs/graph.md | 6 +-
docs/iiif.md | 16 +-
docs/mcp.md | 26 +-
docs/notes.md | 6 +-
docs/notifications.md | 6 +-
docs/podcasts.md | 14 +-
docs/processing.md | 62 +--
docs/rdf.md | 34 +-
docs/sensors.md | 2 +-
docs/storage.md | 2 +-
docs/telemetry.md | 4 +-
docs/topics.md | 56 +--
fastapi_backend/app/api/deps.py | 2 +-
fastapi_backend/app/api/iiif.py | 2 +-
fastapi_backend/app/api/mcp.py | 4 +-
fastapi_backend/app/api/mcp_tools.py | 72 ++--
fastapi_backend/app/api/v1/routes/activity.py | 2 +-
fastapi_backend/app/api/v1/routes/admin.py | 6 +-
fastapi_backend/app/api/v1/routes/batches.py | 6 +-
.../app/api/v1/routes/collections.py | 10 +-
fastapi_backend/app/api/v1/routes/entities.py | 4 +-
.../app/api/v1/routes/entity_setup.py | 2 +-
.../app/api/v1/routes/hierarchy.py | 6 +-
fastapi_backend/app/api/v1/routes/iiif.py | 8 +-
.../app/api/v1/routes/import_hooks.py | 2 +-
fastapi_backend/app/api/v1/routes/jobs.py | 6 +-
fastapi_backend/app/api/v1/routes/metadata.py | 6 +-
.../app/api/v1/routes/namespaces.py | 10 +-
fastapi_backend/app/api/v1/routes/notebook.py | 4 +-
fastapi_backend/app/api/v1/routes/notes.py | 12 +-
.../app/api/v1/routes/pipelines.py | 2 +-
fastapi_backend/app/api/v1/routes/podcasts.py | 2 +-
fastapi_backend/app/api/v1/routes/public.py | 20 +-
fastapi_backend/app/api/v1/routes/rdf.py | 8 +-
.../app/api/v1/routes/recordings.py | 80 ++--
fastapi_backend/app/api/v1/routes/requests.py | 4 +-
fastapi_backend/app/api/v1/routes/search.py | 4 +-
fastapi_backend/app/api/v1/routes/searches.py | 2 +-
fastapi_backend/app/api/v1/routes/sources.py | 2 +-
.../app/api/v1/routes/templates.py | 2 +-
fastapi_backend/app/api/v1/routes/topics.py | 16 +-
fastapi_backend/app/api/v1/routes/uploads.py | 18 +-
.../app/api/v1/routes/workflows.py | 4 +-
fastapi_backend/app/cli.py | 12 +-
fastapi_backend/app/domain/ai_tools.py | 40 +-
fastapi_backend/app/domain/auto_scope.py | 2 +-
fastapi_backend/app/domain/batches.py | 4 +-
fastapi_backend/app/domain/chat.py | 6 +-
fastapi_backend/app/domain/custom_nodes.py | 2 +-
fastapi_backend/app/domain/evidence.py | 2 +-
fastapi_backend/app/domain/graph_ask.py | 4 +-
fastapi_backend/app/domain/graph_model.py | 2 +-
fastapi_backend/app/domain/hierarchy.py | 4 +-
fastapi_backend/app/domain/iiif_auth.py | 6 +-
fastapi_backend/app/domain/ipgroups.py | 2 +-
fastapi_backend/app/domain/jobs.py | 4 +-
fastapi_backend/app/domain/library.py | 2 +-
fastapi_backend/app/domain/metadata.py | 4 +-
fastapi_backend/app/domain/notes.py | 2 +-
fastapi_backend/app/domain/notify.py | 2 +-
fastapi_backend/app/domain/ops_tools.py | 8 +-
fastapi_backend/app/domain/organize.py | 2 +-
fastapi_backend/app/domain/rdf.py | 2 +-
fastapi_backend/app/domain/rdf_import.py | 2 +-
fastapi_backend/app/domain/render.py | 2 +-
fastapi_backend/app/domain/routines.py | 8 +-
.../domain/templates/report_namespace.html | 8 +-
fastapi_backend/app/domain/uploads.py | 2 +-
fastapi_backend/app/domain/workflows.py | 2 +-
fastapi_backend/app/email.py | 4 +-
.../app/email_templates/access_request.html | 4 +-
fastapi_backend/app/schemas/admin.py | 6 +-
fastapi_backend/app/schemas/batches.py | 6 +-
fastapi_backend/app/schemas/chats.py | 4 +-
fastapi_backend/app/schemas/collections.py | 2 +-
fastapi_backend/app/schemas/entity_setup.py | 4 +-
fastapi_backend/app/schemas/hierarchy.py | 8 +-
fastapi_backend/app/schemas/iiif.py | 4 +-
fastapi_backend/app/schemas/import_hooks.py | 4 +-
fastapi_backend/app/schemas/jobs.py | 8 +-
fastapi_backend/app/schemas/metadata.py | 2 +-
fastapi_backend/app/schemas/namespaces.py | 20 +-
fastapi_backend/app/schemas/notes.py | 10 +-
fastapi_backend/app/schemas/ns_assistant.py | 6 +-
fastapi_backend/app/schemas/podcasts.py | 4 +-
fastapi_backend/app/schemas/public.py | 30 +-
fastapi_backend/app/schemas/rdf.py | 2 +-
fastapi_backend/app/schemas/recordings.py | 20 +-
fastapi_backend/app/schemas/routines.py | 2 +-
fastapi_backend/app/schemas/search.py | 8 +-
fastapi_backend/app/schemas/sources.py | 2 +-
fastapi_backend/app/schemas/topics.py | 6 +-
fastapi_backend/app/schemas/uploads.py | 14 +-
fastapi_backend/app/schemas/views.py | 8 +-
fastapi_backend/app/schemas/workflows.py | 2 +-
fastapi_backend/tests/api/test_chats.py | 2 +-
fastapi_backend/tests/api/test_decisions.py | 2 +-
fastapi_backend/tests/api/test_delete.py | 2 +-
fastapi_backend/tests/api/test_evidence.py | 2 +-
fastapi_backend/tests/api/test_mcp.py | 2 +-
fastapi_backend/tests/api/test_notes.py | 2 +-
.../__tests__/access-model.test.ts | 10 +-
.../__tests__/batches-collections.test.ts | 2 +-
nextjs-frontend/__tests__/chat.test.tsx | 2 +-
.../__tests__/fields-model.test.ts | 2 +-
.../__tests__/home-reports.test.ts | 6 +-
.../__tests__/library-collections-ui.test.tsx | 6 +-
.../__tests__/library-collections.test.ts | 8 +-
.../__tests__/library-model.test.ts | 14 +-
.../__tests__/library-views.test.ts | 12 +-
.../__tests__/public-model.test.ts | 4 +-
nextjs-frontend/__tests__/rdf-ui.test.tsx | 8 +-
.../__tests__/recording-chat-tab.test.tsx | 2 +-
.../__tests__/recording-model.test.ts | 2 +-
.../__tests__/recording-notes.test.ts | 2 +-
.../__tests__/routines-model.test.ts | 8 +-
nextjs-frontend/__tests__/search.test.ts | 4 +-
.../__tests__/settings-admin-models.test.ts | 2 +-
.../__tests__/speakers-graph-batches.test.ts | 8 +-
.../app/(app)/resources/[id]/page.tsx | 2 +-
nextjs-frontend/app/(public)/explore/page.tsx | 2 +-
.../(public)/explore/recordings/[id]/page.tsx | 6 +-
nextjs-frontend/app/openapi-client/sdk.gen.ts | 206 ++++-----
.../app/openapi-client/types.gen.ts | 202 ++++-----
.../components/access/access-fields.tsx | 4 +-
.../components/access/ip-groups.tsx | 8 +-
nextjs-frontend/components/access/model.ts | 6 +-
.../components/activity/job-detail.tsx | 16 +-
.../components/activity/runs-view.tsx | 14 +-
.../components/activity/workers-view.tsx | 2 +-
.../components/admin/audit-model.ts | 4 +-
nextjs-frontend/components/admin/health.tsx | 4 +-
.../components/admin/namespaces.tsx | 12 +-
.../components/app-shell/activity.tsx | 4 +-
.../components/app-shell/app-shell.tsx | 4 +-
.../components/app-shell/command-palette.tsx | 10 +-
.../app-shell/namespace-switcher.tsx | 2 +-
.../components/app-shell/shortcuts.tsx | 2 +-
.../assistant/ns-assistant-section.tsx | 2 +-
.../components/batches/batch-list.tsx | 2 +-
.../components/batches/batch-page.tsx | 14 +-
nextjs-frontend/components/batches/format.ts | 12 +-
.../components/batches/report-view.tsx | 4 +-
.../components/batches/results-table.tsx | 8 +-
nextjs-frontend/components/batches/run-on.tsx | 31 +-
nextjs-frontend/components/chat/answer.tsx | 6 +-
nextjs-frontend/components/chat/approval.tsx | 2 +-
nextjs-frontend/components/chat/citation.tsx | 2 +-
nextjs-frontend/components/chat/cite.ts | 2 +-
nextjs-frontend/components/chat/composer.tsx | 8 +-
.../components/chat/conversations.tsx | 2 +-
nextjs-frontend/components/chat/empty.tsx | 2 +-
nextjs-frontend/components/chat/scope.ts | 10 +-
nextjs-frontend/components/chat/sources.tsx | 2 +-
.../collections/collection-detail.tsx | 24 +-
.../collections/collection-dialog.tsx | 14 +-
.../collections/collections-page.tsx | 4 +-
.../components/collections/report-setup.tsx | 12 +-
.../components/entities/define-dialog.tsx | 2 +-
.../components/entities/entities-page.tsx | 8 +-
.../components/entities/entity-drawer.tsx | 4 +-
nextjs-frontend/components/entities/model.ts | 2 +-
.../components/entities/setup-tab.tsx | 10 +-
.../components/errors/error-states.tsx | 4 +-
.../components/graph/graph-page.tsx | 4 +-
nextjs-frontend/components/graph/model.ts | 2 +-
nextjs-frontend/components/graph/panel.tsx | 2 +-
nextjs-frontend/components/home/attention.ts | 6 +-
.../components/home/home-screen.tsx | 8 +-
.../components/home/welcome-tour.tsx | 2 +-
nextjs-frontend/components/iiif/bulk-edit.tsx | 6 +-
.../components/iiif/collection-data.ts | 2 +-
.../components/iiif/collection-page.tsx | 18 +-
.../components/iiif/collections.tsx | 2 +-
nextjs-frontend/components/iiif/import.tsx | 6 +-
.../components/iiif/metadata-editor.tsx | 4 +-
.../components/iiif/metadata-fields.tsx | 4 +-
.../components/iiif/profile-editor.tsx | 12 +-
nextjs-frontend/components/iiif/rdf.tsx | 12 +-
.../components/import/paste-tab.tsx | 4 +-
.../components/import/upload-tab.tsx | 4 +-
nextjs-frontend/components/library/actions.ts | 10 +-
.../components/library/bulk-bar.tsx | 41 +-
.../components/library/collections-model.ts | 4 +-
.../components/library/collections-ui.tsx | 10 +-
.../components/library/filters-bar.tsx | 8 +-
.../components/library/library-empty.tsx | 4 +-
.../components/library/library-screen.tsx | 27 +-
nextjs-frontend/components/library/model.ts | 12 +-
.../components/library/recording-list.tsx | 6 +-
.../components/library/recording-table.tsx | 4 +-
.../components/library/use-collections.ts | 6 +-
.../components/library/views-model.ts | 2 +-
.../components/notes/notes-home.tsx | 4 +-
.../components/pipelines/pipeline-canvas.tsx | 6 +-
.../components/pipelines/pipeline-editor.tsx | 16 +-
.../components/pipelines/pipeline-model.ts | 2 +-
.../components/pipelines/step-settings.tsx | 4 +-
.../components/player/transport.tsx | 2 +-
.../components/podcasts/podcasts-screen.tsx | 3 +-
nextjs-frontend/components/public/cards.tsx | 2 +-
.../components/public/explore-views.tsx | 14 +-
nextjs-frontend/components/public/model.ts | 4 +-
.../components/public/recording-view.tsx | 14 +-
.../components/public/request-access.tsx | 2 +-
.../components/public/search-view.tsx | 6 +-
nextjs-frontend/components/public/states.tsx | 2 +-
.../components/recording/chapters.tsx | 2 +-
.../components/recording/chat-tab.tsx | 14 +-
.../components/recording/comments-tab.tsx | 6 +-
.../components/recording/details-tab.tsx | 2 +-
.../components/recording/dialogs.tsx | 4 +-
.../components/recording/header.tsx | 12 +-
.../components/recording/history-tab.tsx | 6 +-
nextjs-frontend/components/recording/hooks.ts | 2 +-
nextjs-frontend/components/recording/jobs.ts | 4 +-
.../components/recording/mobile-layout.tsx | 2 +-
nextjs-frontend/components/recording/model.ts | 2 +-
.../components/recording/notes-model.ts | 2 +-
.../components/recording/notes-tab.tsx | 10 +-
.../components/recording/recording-page.tsx | 4 +-
.../components/recording/side-panel.tsx | 4 +-
.../components/recording/skeleton.tsx | 2 +-
.../components/recording/summary-tab.tsx | 2 +-
.../components/recording/transcript.tsx | 2 +-
nextjs-frontend/components/reports/model.ts | 2 +-
.../components/reports/month-bars.tsx | 8 +-
.../components/reports/namespace-overview.tsx | 10 +-
.../components/reports/recording-report.tsx | 12 +-
.../components/reports/reports-screen.tsx | 4 +-
.../components/routines/routine-editor.tsx | 6 +-
.../components/routines/routine-model.ts | 8 +-
.../components/routines/routines-page.tsx | 4 +-
.../components/search/facet-panel.tsx | 2 +-
nextjs-frontend/components/search/facets.ts | 4 +-
.../components/search/no-results.tsx | 8 +-
nextjs-frontend/components/search/player.tsx | 4 +-
nextjs-frontend/components/search/query.ts | 2 +-
nextjs-frontend/components/search/results.tsx | 2 +-
.../components/search/save-search.tsx | 4 +-
.../components/search/search-page.tsx | 8 +-
.../components/search/syntax-help.tsx | 2 +-
nextjs-frontend/components/sensors/parts.tsx | 2 +-
.../components/settings/bodies.tsx | 18 +-
nextjs-frontend/components/settings/model.ts | 20 +-
.../components/settings/section.tsx | 2 +-
.../components/setup/setup-wizard.tsx | 2 +-
.../components/sharing/embed-builder.tsx | 4 +-
.../components/sharing/share-dialog.tsx | 6 +-
.../components/sharing/share-links.tsx | 6 +-
.../components/sources/connection-dialog.tsx | 2 +-
.../components/sources/delete-connection.tsx | 2 +-
.../components/sources/watch-editor.tsx | 2 +-
.../components/templates/new-template.tsx | 2 +-
.../components/templates/template-editor.tsx | 12 +-
.../components/templates/templates-page.tsx | 2 +-
.../components/topics/topic-candidates.tsx | 4 +-
.../components/topics/topic-drawer.tsx | 16 +-
.../components/topics/topics-page.tsx | 10 +-
.../workflows/custom-node-editor.tsx | 2 +-
.../workflows/custom-nodes-page.tsx | 2 +-
.../components/workflows/node-settings.tsx | 9 +-
.../components/workflows/workflow-editor.tsx | 20 +-
.../components/workflows/workflow-model.ts | 19 +-
nextjs-frontend/openapi.json | 392 +++++++++---------
threat-model.json | 26 +-
threat-model.md | 38 +-
threat-model.yaml | 40 +-
287 files changed, 1598 insertions(+), 1629 deletions(-)
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 5241af4d9..5065d11b5 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -14,7 +14,7 @@ body:
attributes:
label: Steps to reproduce
placeholder: |
- 1. Open a recording in a namespace with …
+ 1. Open an asset in a namespace with …
2. Click …
validations:
required: true
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 99bc0b17a..90ff0eba6 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,4 +1,4 @@
-
## Description
diff --git a/CHANGELOG.md b/CHANGELOG.md
index cc72becd8..309249435 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,9 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
anytopdf, telemetry), takes the administrator password when installing needs it, then installs with live progress
and opens Lens's setup page. Its answers become ordinary settings in Lens, editable there
([Get started](docs/get-started.md#the-web-installer)). `LENS_WIZARD=0` keeps the install in the terminal.
+- **Assets, not recordings.** The web app, the assistant, the API descriptions and the docs now call an item of any
+ kind an asset (or a document, when it is one), and keep "recording" for audio and video. API paths, MCP tool names
+ and stored data are unchanged.
## 0.6.0 October 10, 2026 {id="0.6.0"}
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index afdb46cba..2ca608455 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,7 +27,7 @@ Use [Conventional Commits](https://www.conventionalcommits.org/): `type(optional
the colon for a breaking change.
```
-feat(chat): answer from the selected recordings
+feat(chat): answer from the selected assets
fix(worker): retry a stalled transcription
docs: explain the Synology package
feat(api)!: drop the v1 recordings endpoint
diff --git a/README.md b/README.md
index 748d66074..4ddd9484c 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@ what their person may read.
- **Understand it.** Transcription and speaker recognition, entities and topics in a knowledge graph you can explore,
query with Cypher or SPARQL, and see as it was at any version. ([Graph](docs/graph.md),
[graph history](docs/graph-history.md), [topics](docs/topics.md), [video](docs/video.md))
-- **Keep notes beside it.** Every recording, entity and topic has a page, plus free notes that you and the assistant
+- **Keep notes beside it.** Every asset, entity and topic has a page, plus free notes that you and the assistant
write and link. ([Notes](docs/notes.md))
- **Automate it.** Pipelines and workflows on a canvas, routines on a schedule, and extensions (prompts, templates and
sandboxed Python) the assistant can call.
diff --git a/docs/access.md b/docs/access.md
index feb060d1c..78f1f8545 100644
--- a/docs/access.md
+++ b/docs/access.md
@@ -1,24 +1,24 @@
-# Access: who sees which recordings
+# Access: who sees which assets
-Lens follows the roles and permissions matrix of Aviary, the audio and video access platform: every recording is
-**public**, **restricted** or **private**, can be **featured**, and a public recording can keep some of its parts
+Lens follows the roles and permissions matrix of Aviary, the audio and video access platform: every asset is
+**public**, **restricted** or **private**, can be **featured**, and a public asset can keep some of its parts
closed. Who may open what depends on who is asking.
-## A recording's access
+## An asset's access
| Setting | Values | Default |
|---|---|---|
| `access` | `public`, `restricted` or `private` | the namespace's default access, else `private` |
-| `open` | the parts of a public recording anyone may use: `media` (audio or video, frames; a document's or an image's pages and its file), `transcript` (the text with who said what, its search and downloads) and `index` (chapters, or a document's sections) | the namespace's default parts, else all three |
+| `open` | the parts of a public asset anyone may use: `media` (audio or video, frames; a document's or an image's pages and its file), `transcript` (the text with who said what, its search and downloads) and `index` (chapters, or a document's sections) | the namespace's default parts, else all three |
| `featured` | shown on the home page when public | no |
-A recording's **description** (its descriptive metadata: title, date, summary, speakers, subjects, rights) is never a
-closed part: whoever may see the recording's page sees it, as IIIF manifests always have.
+An asset's **description** (its descriptive metadata: title, date, summary, speakers, subjects, rights) is never a
+closed part: whoever may see the asset's page sees it, as IIIF manifests always have.
-Publishing is for owners: they set a recording's access, open parts and featured flag (in its Access dialog, or
+Publishing is for owners: they set an asset's access, open parts and featured flag (in its Access dialog, or
through its metadata, bulk edits and reverts), and their namespace's default access and parts in its metadata
profile. Editors edit the rest of the metadata. Every change is kept in the metadata history and can be reverted.
-Moving a recording to another namespace doesn't change who sees it: the access it had from its old namespace is pinned
+Moving an asset to another namespace doesn't change who sees it: the access it had from its old namespace is pinned
on it.
## Files
@@ -35,13 +35,13 @@ Flow.
| In the matrix | In Lens |
|---|---|
| public user | a visitor who isn't signed in |
-| public user with view permission in an IP group | a visitor whose address is in an IP group with view permission on the recording or its namespace |
-| registered user | a signed-in person with no role in the recording's namespace and no permission on it |
-| registered user with view or edit permission | a signed-in person given permission on the recording (below) |
-| organization user, admin, owner | a member of the recording's namespace (viewer, editor or owner), and admins everywhere |
+| public user with view permission in an IP group | a visitor whose address is in an IP group with view permission on the asset or its namespace |
+| registered user | a signed-in person with no role in the asset's namespace and no permission on it |
+| registered user with view or edit permission | a signed-in person given permission on the asset (below) |
+| organization user, admin, owner | a member of the asset's namespace (viewer, editor or owner), and admins everywhere |
-Members, people given permission and IP-group visitors have **permission**: they see the recording everywhere and open all of
-it. Everyone else gets what the recording's access allows:
+Members, people given permission and IP-group visitors have **permission**: they see the asset everywhere and open all of
+it. Everyone else gets what the asset's access allows:
| | Public user | Registered user | With permission |
|---|---|---|---|
@@ -49,13 +49,13 @@ it. Everyone else gets what the recording's access allows:
| **restricted** | hidden | listed with a lock ("content locked"); the page stays closed; can request access | everything |
| **private** | hidden | hidden | everything |
-The home page shows featured public recordings only, to everyone, members included.
+The home page shows featured public assets only, to everyone, members included.
-## Permission on a recording
+## Permission on an asset
-Owners give someone permission on one recording in its Access dialog, by the email address of their account (an admin
-creates accounts), and take it away there; both are audited. With permission, a person sees all of the recording on
-the pages for visitors, whatever its access: a private recording is listed for them in its collection and in search,
+Owners give someone permission on one asset in its Access dialog, by the email address of their account (an admin
+creates accounts), and take it away there; both are audited. With permission, a person sees all of the asset on
+the pages for visitors, whatever its access: a private asset is listed for them in its collection and in search,
and under "Shared with you" on the home page. IIIF lets them in too: its manifest with their token or the IIIF access
cookie, and its media and transcript through the Authorization Flow. Face crops stay with members unless the namespace
publishes them. Permission doesn't open the workspace: that stays with the namespace's members.
@@ -64,14 +64,14 @@ In the matrix, view and edit permission open the same pages; Lens has one permis
## Collection roles
-Every recording lives in a collection of its namespace ([API](api.md#collections-of-a-namespace)), and people can be
+Every asset lives in a collection of its namespace ([API](api.md#collections-of-a-namespace)), and people can be
given a role on a collection: **viewer**, **editor** or **admin**. A role holds for the collections inside it too, and
adds to a namespace role, never takes from it: a viewer of the namespace who is an editor of one collection edits its
-recordings and only reads the rest.
+assets and only reads the rest.
| | Viewer | Editor | Admin |
|---|---|---|---|
-| its recordings | see and search them, open their pages, write their own notes | and edit them: transcript, catalogue record, tags, collection, notes for everyone, reprocessing | and act as their owner: access and featured, permission, deleting |
+| its assets | see and search them, open their pages, write their own notes | and edit them: transcript, catalogue record, tags, collection, notes for everyone, reprocessing | and act as their owner: access and featured, permission, deleting |
| the collection | — | — | rename, describe, move it within what they're an admin of, make and delete collections inside it, give roles on it |
Owners of the namespace give roles on any of its collections, admins of a collection on it and the ones inside it
@@ -80,19 +80,19 @@ collections; the top of the namespace and its default collection stay theirs. Gi
is audited as `collection.member`. Deleting a collection (only when it's empty) takes the roles given on it.
Someone **without a role in the namespace** who has a role on some of its collections sees just those: their
-recordings in the Library (the namespace is marked "Some"), in search and on the recordings' pages, and the
+assets in the Library (the namespace is marked "Some"), in search and on the assets' pages, and the
collections in the Library's Collection filter, starting from the ones they were given. The namespace's own pages
(Home's numbers, Speakers, Graph, Reports, Chat, Activity, Batches) stay with the namespace's members, so nothing outside their
-collections shows: those pages say so when such a namespace is picked. On a recording, the entities it mentions are
-counted over the recordings they see; the namespace's lists of speakers and faces stay with its members, and renaming
+collections shows: those pages say so when such a namespace is picked. On an asset, the entities it mentions are
+counted over the assets they see; the namespace's lists of speakers and faces stay with its members, and renaming
or merging speakers and faces (which are the namespace's) needs editor access to the namespace. For the pages
-visitors see and IIIF, a role on a collection is permission on its recordings.
+visitors see and IIIF, a role on a collection is permission on its assets.
## Asking for access
-Someone signed in without permission can ask a recording's owners for access: to the closed parts of a public
-recording, or to a restricted one (on its "content locked" page), with a message if they like. The namespace's owners
-(admins, when it has none) get an email when mail is set up, and see the request in the recording's Access dialog and
+Someone signed in without permission can ask an asset's owners for access: to the closed parts of a public
+asset, or to a restricted one (on its "content locked" page), with a message if they like. The namespace's owners
+(admins, when it has none) get an email when mail is set up, and see the request in the asset's Access dialog and
on Home under Needs attention. Approving gives the person permission; declining lets them ask again. The page tells
them where their request stands. Asking again while a request waits only updates its message, and emails the owners
at most once a day; answers are audited.
@@ -101,11 +101,11 @@ at most once a day; answers are audited.
Owners give a network permission on their namespace's page (Admin → Namespaces), under **IP groups**: a name that
visitors see (a reading room, a campus), its addresses (single addresses or CIDR ranges, none wider than `/8` for IPv4
-or `/16` for IPv6), and what the group opens: every recording in the namespace, now and later, or the recordings chosen
+or `/16` for IPv6), and what the group opens: every asset in the namespace, now and later, or the assets chosen
in each one's Access dialog. A visitor whose address is in a group sees what it opens as if they had permission,
without signing in: listed in its collection and in search, all of its page, and in IIIF (manifests, content,
collections, and the Authorization Flow's probe). The page tells them why ("You're connecting from Reading room").
-Adding, changing and deleting groups, and opening or closing a recording to one, are audited.
+Adding, changing and deleting groups, and opening or closing an asset to one, are audited.
IP groups need the server to know the visitor's address. Behind the web app, that is what the web app and the proxies
in front of it report in `X-Forwarded-For`, which the server believes only from `server.trusted_proxies` (see
@@ -119,39 +119,39 @@ section shows your address as the server sees it and marks the groups that hold
| Home, featured resources | the public home page, `/explore` |
| Collection splash page, all resources | a namespace's public page, `/explore/collections/` |
| Search results page | public search, `/explore/search?q=` |
-| Resource detail page | a recording's public page, `/explore/recordings/` (members open it in the workspace too) |
+| Resource detail page | an asset's public page, `/explore/recordings/` (members open it in the workspace too) |
-**The home page** shows the featured public recordings, to everyone, and the collections the visitor can see anything
+**The home page** shows the featured public assets, to everyone, and the collections the visitor can see anything
in. **A collection's page** has the namespace's label, summary, rights and provider (its IIIF metadata) and the
-recordings the visitor sees, newest first: public ones for everyone, restricted ones with a lock ("content locked" over
+assets the visitor sees, newest first: public ones for everyone, restricted ones with a lock ("content locked" over
the picture) for people who are signed in, and all of them for members and for visitors from an IP group that opens
the namespace. A collection with nothing for the visitor
isn't there for them. The sign-in page links to the home page.
-**Search** finds the recordings the visitor sees by their title, and by the lines of the transcripts they may read,
-title matches first; each line links to its moment in the recording. A restricted recording (for signed-in people) and
+**Search** finds the assets the visitor sees by their title, and by the lines of the transcripts they may read,
+title matches first; each line links to its moment in the recording. A restricted asset (for signed-in people) and
a public one whose transcript is closed match on their title only, so a search never reveals what they say.
-**A recording's public page** shows what the visitor may see: its title, date and description, and each open part: the
+**An asset's public page** shows what the visitor may see: its title, date and description, and each open part: the
player, the transcript (with find in the transcript, and its files to download), the chapters, and the supplementary
files open to them. A closed part says who can open it and offers visitors to sign in; signing in comes back to the
-page. Signed-in people without permission see a restricted recording's title behind a lock ("content locked"); members
+page. Signed-in people without permission see a restricted asset's title behind a lock ("content locked"); members
see all of it, with a link to the workspace. `?t=` opens it at a moment. Owners find the link to share in a
-public recording's Access dialog. The page is left out of search engines unless the recording is public.
+public asset's Access dialog. The page is left out of search engines unless the asset is public.
-The workspace (Library, recording pages, Search, Chat and the rest) stays as it is: namespaces you have no role in
-never appear there, and grant holders see the recordings shared with them.
+The workspace (Library, asset pages, Search, Chat and the rest) stays as it is: namespaces you have no role in
+never appear there, and grant holders see the assets shared with them.
## What IIIF publishes
-IIIF follows the same setting. A public recording's manifest is open; its media and transcript are plain links when
+IIIF follows the same setting. A public asset's manifest is open; its media and transcript are plain links when
those parts are open, otherwise they sit behind the IIIF Authorization Flow, which admits people with permission
(visitors from an IP group's addresses need no sign-in). Chapters appear as ranges when the index is open. Supplementary
files follow their parts the same way (see Files), and custom fields appear only when published ([API](api.md#fields)).
-Restricted and private recordings are not published: their manifests answer 404 unless the request carries permission,
+Restricted and private assets are not published: their manifests answer 404 unless the request carries permission,
and they are left out of collections. Where a namespace pixelates faces for visitors ([Video](video.md)), its frames
and pages come through IIIF with the faces found pixelated, unless the request (or the IIIF access cookie's account)
-has a role in the namespace. Change Discovery announces a **Create** when a recording becomes public, an
+has a role in the namespace. Change Discovery announces a **Create** when an asset becomes public, an
**Update** when a public one changes, and a **Delete** when it stops being public.
## Moving from the IIIF access levels
@@ -165,5 +165,5 @@ Lens used to set access for IIIF only, with four levels. The first start of this
| `signed-in` (listed, content after sign-in) | `restricted` |
| `private` | `private` |
-Namespace defaults convert the same way. Recordings that were `signed-in` were listed in IIIF and no longer are, so the
+Namespace defaults convert the same way. Assets that were `signed-in` were listed in IIIF and no longer are, so the
conversion announces a Delete for each of them. Old metadata history entries convert when they are reverted.
diff --git a/docs/activity.md b/docs/activity.md
index 2aece1914..ed2d280c7 100644
--- a/docs/activity.md
+++ b/docs/activity.md
@@ -11,13 +11,13 @@ Each row names every resource it counts for, as `table:id`:
| Resource | Example |
| --- | --- |
| A routine and one of its runs | `routine:3`, `routine_run:12` |
-| A job, its recording, namespace and pipeline | `job:40`, `recording:7`, `space:1`, `pipeline:2` |
+| A job, its asset, namespace and pipeline | `job:40`, `recording:7`, `space:1`, `pipeline:2` |
| A workflow | `workflow:4` |
| A chat | `chat:9` |
| A note (its refinement and filing, and the requests that changed it) | `note_page:5` |
| The person who asked | `account:1` |
-A model call inside a workflow step of a job that a routine queued counts for the workflow, the job, the recording,
+A model call inside a workflow step of a job that a routine queued counts for the workflow, the job, the asset,
its namespace, its pipeline and the routine. A request counts for the resources in its path (`PATCH
/api/v1/routines/3` is `routine:3`), for what a `POST` made (from the `id` in its reply), and for who sent it.
@@ -66,7 +66,7 @@ GET /api/v1/activity/totals?period=day # everything (admins)
GET /api/v1/activity/top?table=routine&period=week # what cost most (admins)
```
-Admins see every resource. Everyone else sees their own account's activity, their own chats', and the recordings and
+Admins see every resource. Everyone else sees their own account's activity, their own chats', and the assets and
namespaces they can read.
## Settings
diff --git a/docs/api.md b/docs/api.md
index 8d862bc80..2b87ec3c0 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -149,8 +149,8 @@ POST /api/v1/admin/semantic/index
```
`POST /settings/embeddings/test` embeds one sentence with the configured embedding model (`dimension`, `ms`, or the
-`error`). `GET /admin/semantic` says whether search by meaning is set up, with which model, and how many recordings
-and passages are indexed with it; `POST /admin/semantic/index?limit=500` queues the embed step for recordings not yet
+`error`). `GET /admin/semantic` says whether search by meaning is set up, with which model, and how many assets
+and passages are indexed with it; `POST /admin/semantic/index?limit=500` queues the embed step for assets not yet
indexed with it (`remaining` when more are waiting). The other `test` endpoints try the saved settings of their
section (mail, file store, speech provider, decision model, telemetry, bridge) and answer what happened or the
`error`; the `status` endpoints say how that part is doing. All are for admins.
@@ -205,7 +205,7 @@ PATCH /api/v1/custom-nodes/{nid}
DELETE /api/v1/custom-nodes/{nid}
```
-Content types (admins change them; everyone reads them) say what kind of thing a recording is, and a recording's
+Content types (admins change them; everyone reads them) say what kind of thing an asset is, and an asset's
`content-type` sets it. Custom nodes are versioned steps people write for workflows (`?scope=` filters the list,
`?version=` reads an older one).
@@ -267,17 +267,17 @@ some collections of: `partial: true`, no `role`, counted over those collections,
cloud and speakers.
`/namespaces/{name}/stats?from=&to=&top=` gives the Reports overview its numbers (viewers of the namespace): the
-recordings made from `from` to `to` (days, `YYYY-MM-DD`, both included; leave either open), how many and how long
+assets made from `from` to `to` (days, `YYYY-MM-DD`, both included; leave either open), how many and how long
(`recordings`, `ms`), how many speakers are heard in them and the `top` ones by talk time in them (`top_speakers`,
default 5, at most 50, each with `talk_ms` and `recordings`), the days of the `first` and `last`, and `months`: every
-calendar month from `from` (else the first recording) to `to` (else the later of today and the last recording),
-empty ones included, at most the latest 240. Without a range it counts every recording; `undated` says how many
-have no date, and those are never in a month or a range. Months and days are the recording dates as stored (the
+calendar month from `from` (else the first asset) to `to` (else the later of today and the last asset),
+empty ones included, at most the latest 240. Without a range it counts every asset; `undated` says how many
+have no date, and those are never in a month or a range. Months and days are the asset dates as stored (the
time where it was recorded). 400 when `to` comes before `from`.
`/namespaces/{name}/ip-groups` lists a namespace's IP groups ([Access](access.md#ip-groups), owners), with `address`:
your address as the server sees it (`null` when it can't tell; see `server.trusted_proxies`), and on each group `here`
-(your address is in it) and `chosen` (how many recordings it opens when it doesn't open `everything`). `POST` with
+(your address is in it) and `chosen` (how many assets it opens when it doesn't open `everything`). `POST` with
`{"name", "ranges", "everything"}` adds one: `ranges` are addresses or CIDR ranges, at most 100, none wider than `/8`
(IPv4) or `/16` (IPv6); names are unique in the namespace. `PATCH` changes any of them and `DELETE` removes the group.
All three answer with the list and are audited as `namespace.ip_group.create`, `.update` and `.delete`.
@@ -294,21 +294,21 @@ answer `code` and `error`. Changes are audited as `namespace.notification.create
### Collections of a namespace
-Every recording lives in exactly one collection of its namespace, and collections nest (at most 8 deep, 5000 per
-namespace). Each namespace has a default collection, "General" when it's made, where recordings go when nobody says
-where: imports, uploads, scans, watched folders and recordings moved in from another namespace. Existing recordings
+Every asset lives in exactly one collection of its namespace, and collections nest (at most 8 deep, 5000 per
+namespace). Each namespace has a default collection, "General" when it's made, where assets go when nobody says
+where: imports, uploads, scans, watched folders and assets moved in from another namespace. Existing assets
were put in their namespace's General when collections came in. (Saved collections, under
-[collections](#collections), are something else: lists of recordings from anywhere.)
+[collections](#collections), are something else: lists of assets from anywhere.)
`GET /namespaces/{name}/collections` lists them depth first, by name (viewers): each with its `parent` (`null` at the
-top), `depth`, `path` (names from the top down), how many recordings it holds (`recordings`) and holds with the
+top), `depth`, `path` (names from the top down), how many assets it holds (`recordings`) and holds with the
collections inside it (`total`), how many collections are directly inside it (`children`), and `default`.
`POST {name, parent?, description?}` makes one (editors); a name is unique among the collections next to it, ignoring
case and repeated spaces. `PATCH` renames it, describes it, moves it inside another collection of the namespace
-(`parent`; `null`: to the top; not inside itself), with the recordings and collections in it, or makes it the default
+(`parent`; `null`: to the top; not inside itself), with the assets and collections in it, or makes it the default
(`default: true`; `false` on the default is a 400: make another one the default instead). `DELETE` removes an empty
-collection: 409 while it holds recordings or collections, or is the default, so deleting one never takes a
-recording with it. Audited as `collection.create`, `collection.update` (with what changed) and `collection.delete`.
+collection: 409 while it holds assets or collections, or is the default, so deleting one never takes an
+asset with it. Audited as `collection.create`, `collection.update` (with what changed) and `collection.delete`.
In IIIF each collection is a Collection inside its namespace's ([IIIF](iiif.md)).
People can be given a role on a collection, which holds for the ones inside it too ([Access](access.md#collection-roles)).
@@ -373,42 +373,42 @@ GET /api/v1/resources/{rid}/edits
GET /api/v1/resources/{rid}/outputs
```
-`GET /resources` filters, sorts and pages on the server, over every recording you can read (in the namespaces you have
+`GET /resources` filters, sorts and pages on the server, over every asset you can read (in the namespaces you have
a role in, and in the collections you were given a role on), each with your `role` on it. Filters combine with AND;
repeat a parameter that takes several values (`?status=new&status=error`) to match any of them.
| Parameter | |
|---|---|
| `ns` | one namespace (default: every namespace you can read) |
-| `collection` | a collection's id: the recordings in it and in the collections inside it |
+| `collection` | a collection's id: the assets in it and in the collections inside it |
| `q` | words that must all appear in the title, the namespace's name or a speaker's name |
| `status` | `new`, `transcribed`, `diarized`, `analyzed`, `error`, and two job states: `processing` (a job is queued or running) and `failed` (the latest job failed) |
-| `attention` | `true`: only recordings that need a person (errored, latest job failed, or a voice match waiting for review) |
-| `processing` | `true`: only recordings with a job queued or running |
+| `attention` | `true`: only assets that need a person (errored, latest job failed, or a voice match waiting for review) |
+| `processing` | `true`: only assets with a job queued or running |
| `speaker` | speaker ids |
-| `from`, `to` | the recording date, `YYYY-MM-DD`, both days included; recordings without a date don't match |
+| `from`, `to` | the asset date, `YYYY-MM-DD`, both days included; assets without a date don't match |
| `min_duration`, `max_duration` | seconds: at least `min_duration`, shorter than `max_duration` |
| `media` | `audio`, `video`, `transcript` (no media), `document` or `image` |
-| `access` | `public`, `restricted` or `private`: the recording's own setting, else its namespace's default |
-| `featured` | `true`: only featured recordings; `false`: only the others |
+| `access` | `public`, `restricted` or `private`: the asset's own setting, else its namespace's default |
+| `featured` | `true`: only featured assets; `false`: only the others |
| `tag` | tags, ignoring case |
| `origin` | where they came from: `source:` (a connected source), `upload`, `paste`, `iiif`, `folder` (the archive's own folders) or `file` (another file imported by path) |
-| `language` | language codes, ignoring case; `none` for recordings whose language isn't known |
+| `language` | language codes, ignoring case; `none` for assets whose language isn't known |
| `object` | kinds of object seen in them (`person`, `car` …; [Objects](#objects)), ignoring case |
-| `edited_by` | `me`: recordings you edited (corrected a line of the transcript, changed the catalogue record, or renamed) |
-| `sort` | `date`, `title`, `duration`, `speakers`, `status` or `importance`; `-` in front for descending (default `-date`). Recordings without the value come last either way |
+| `edited_by` | `me`: assets you edited (corrected a line of the transcript, changed the catalogue record, or renamed) |
+| `sort` | `date`, `title`, `duration`, `speakers`, `status` or `importance`; `-` in front for descending (default `-date`). Assets without the value come last either way |
| `limit`, `offset` | one page (default 500 rows, at most 1000) |
-The body is the page's rows; the `X-Total-Count` header says how many recordings match on all pages.
+The body is the page's rows; the `X-Total-Count` header says how many assets match on all pages.
-Rows also say where each recording came from (`origin`, and `origin_name`: the source's name, or e.g. "Uploaded"),
+Rows also say where each asset came from (`origin`, and `origin_name`: the source's name, or e.g. "Uploaded"),
its `language` when known and the collection it lives in (`collection`, `collection_name`). `GET /resources/{rid}`
adds `collection_path`: the collections from the top of the namespace down to its own, `[{id, name}]`.
-`POST /resources/collection {recordings, collection}` moves recordings into a collection of their namespace (editors
-of each); a recording of another namespace is a 400 (move it to that namespace first). It answers how many `moved`;
+`POST /resources/collection {recordings, collection}` moves assets into a collection of their namespace (editors
+of each); an asset of another namespace is a 400 (move it to that namespace first). It answers how many `moved`;
their IIIF Manifests change (`partOf`), so harvesters see an Update. Audited as `recording.collection`.
`GET /resources/origins`, `GET /resources/languages` and `GET /resources/objects` (`ns` for one namespace) list the
-origins, languages and kinds of object of the recordings you can read with how many have each, most first, for the
+origins, languages and kinds of object of the assets you can read with how many have each, most first, for the
Library's Source, Language and Objects filters.
`PATCH /resources/{rid}/segments/{idx}` corrects a transcript line: its `text`, its `speaker` (an id in the
@@ -419,11 +419,11 @@ keeps the line's speaker unless `speaker` is sent. `POST …/segments/{idx}/merg
texts (with a space between them, none in scripts written without spaces) and their words, from the first's start to
the second's end, with the first's speaker. A split or merge renumbers the lines after it, and what points at line
numbers follows: the edit history, people's entity corrections and the chapters. Each change re-analyses the
-recording (`job`), is audited (`transcript.edit`, `transcript.split`, `transcript.merge`) and is kept in `GET …/edits`,
+asset (`job`), is audited (`transcript.edit`, `transcript.split`, `transcript.merge`) and is kept in `GET …/edits`,
the latest first, with `kind` (`split`, `merge`, or null for a correction); a merge keeps where its second line
started (`after.at`, `after.t`) to split it there again.
-A recording's `summary` (the Summarize step's, also in `GET …/player`) has `summary`, `key_points` and
+An asset's `summary` (the Summarize step's, also in `GET …/player`) has `summary`, `key_points` and
`action_items`, `topics`, `people`, `sentiment` and `importance` (1–5). Key points and action items are
`{text, who?, t0?}`: `who` will do it, and `t0` is where the line they come from starts (ms), when the model said;
summaries made before they had times hold plain strings.
@@ -432,27 +432,27 @@ In `GET …/player`, a line whose words have timings from transcription carries
each word, a character range of its `text` and when it was said (ms). A corrected line keeps the timings of the words
it still has.
-Recordings carry `tags`. `PATCH /resources/{rid}` with `{"tags": [...]}` replaces a recording's tags (editors; at most
+Assets carry `tags`. `PATCH /resources/{rid}` with `{"tags": [...]}` replaces an asset's tags (editors; at most
20, 40 characters each; whitespace is collapsed and repeats are dropped, ignoring case). `POST /resources/tags` with
`{"recordings", "add", "remove"}` changes the tags of several at once (editors of each one's namespace) and says how
-many changed. `GET /resources/tags` (`ns` for one namespace) lists the tags in use with how many recordings have each,
+many changed. `GET /resources/tags` (`ns` for one namespace) lists the tags in use with how many assets have each,
most used first.
-`PATCH /resources/{rid}` with `{"title": …}` renames a recording (editors; whitespace is collapsed, at most 200
-characters). It is audited as `recording.rename`; the recording's report page follows the new title and is rebuilt,
-and a published recording shows up as an Update in the IIIF change feed.
+`PATCH /resources/{rid}` with `{"title": …}` renames an asset (editors; whitespace is collapsed, at most 200
+characters). It is audited as `recording.rename`; the asset's report page follows the new title and is rebuilt,
+and a published asset shows up as an Update in the IIIF change feed.
-`DELETE /resources/{rid}` deletes a recording (owners). Everything Lens made from it goes: its transcript and analysis
+`DELETE /resources/{rid}` deletes an asset (owners). Everything Lens made from it goes: its transcript and analysis
(segments, speakers' turns, chapters, entity mentions, terms, edits), video shots, text on screen, face tracks and
frames, outputs, reports and exports, shares, permissions, requests for access, and its place in IP groups, fixed
collections, chat scopes and batch runs that haven't started it. Speakers and faces only it had are removed unless
someone named them. Its waiting jobs are cancelled; while a job is running on it the answer is 409, and a worker that
-finds its recording gone stops. The media file stays where it is: scans skip the same path and the same file elsewhere,
+finds its asset gone stops. The media file stays where it is: scans skip the same path and the same file elsewhere,
and watched folders skip the same remote file, even when it changes; importing it on purpose (the Import dialog,
-`lens import`, a IIIF manifest) brings it back. A public recording shows up as a Delete in the IIIF change feed. It is
+`lens import`, a IIIF manifest) brings it back. A public asset shows up as a Delete in the IIIF change feed. It is
audited as `recording.delete` with its title, namespace and path.
-`POST /resources/{rid}/move` with `{"namespace", "collection", "rediarize", "revoke_shares"}` moves a recording to
+`POST /resources/{rid}/move` with `{"namespace", "collection", "rediarize", "revoke_shares"}` moves an asset to
another namespace (owners of its namespace, editors of the new one), into `collection` there (default: the new
namespace's default collection; 404 for a collection of another namespace). It keeps its transcript, media, frames, outputs, the people given
permission on it and its share links (`revoke_shares`: they stop working). Its IIIF manifest stays as it was: what it
@@ -462,7 +462,7 @@ by name in the new namespace, or start there with this recording's voice and fac
again from their voices instead); unnamed ones left with nothing in the old namespace are removed. Its entity mentions
and per-mention corrections start over: analysis runs again in the new namespace (`job`). Its report pages and exports
move to the new namespace's folders. The old namespace's scans and watched folders don't import the file again, and
-its IP groups no longer open the recording. 409 when the new namespace already has the same file or a job is running
+its IP groups no longer open the asset. 409 when the new namespace already has the same file or a job is running
on it. Audited as `recording.move`.
Share links (editors): `POST /resources/{rid}/share` with `{"days"}` (1–3650, default 30) makes one and returns its
@@ -472,17 +472,17 @@ hashes are kept, so the addresses are shown this once. `GET /resources/{rid}/sha
none), `plays` (times its player started playing, once per page load; previews in Lens itself don't count) with
`played_at`, and `embedded_on`: the sites whose pages framed its player (`origin`, `opens`, `last_at`, most recent
first, up to 50 per link), from the browser's Referer when it reports a frame. `DELETE /resources/{rid}/shares/{id}`
-revokes one link (404 if the recording has no such link), `DELETE /resources/{rid}/share` every one that still
-works; both are audited as `share.revoke`. A link that doesn't work (expired, revoked, mistyped, or its recording is
-gone) opens a neutral page with status 410 that says nothing about the recording.
+revokes one link (404 if the asset has no such link), `DELETE /resources/{rid}/share` every one that still
+works; both are audited as `share.revoke`. A link that doesn't work (expired, revoked, mistyped, or its asset is
+gone) opens a neutral page with status 410 that says nothing about the asset.
-`GET /resources/{rid}/access` says who may see a recording (members): `access` (`public`, `restricted` or
-`private`), `open` (the parts a public recording opens to everyone: `media`, `transcript`, `index`), `featured`,
+`GET /resources/{rid}/access` says who may see an asset (members): `access` (`public`, `restricted` or
+`private`), `open` (the parts a public asset opens to everyone: `media`, `transcript`, `index`), `featured`,
`inherited` (the access comes from the namespace) and the namespace's `default`. `PUT` changes any of them (owners);
`null` follows the namespace again. Changes are audited as `recording.access`, kept in the metadata history, and
announced in the IIIF change feed. [Access](access.md) explains what each level lets people do.
-`/resources/{rid}/permissions` lists the people given permission on the recording (owners). `POST` with `{"email":
+`/resources/{rid}/permissions` lists the people given permission on the asset (owners). `POST` with `{"email":
…}` gives it to the account with that address (404 when there is none, 400 for members of the namespace, who already
see all of it); `DELETE …/{account}` takes it away. Both answer with the list and are audited as
`recording.permission.give` and `recording.permission.take`. `/resources/{rid}/requests` lists the requests for access
@@ -490,7 +490,7 @@ see all of it); `DELETE …/{account}` takes it away. Both answer with the list
`recording.request.approve` and `recording.request.decline`).
`/resources/{rid}/ip-groups` lists the namespace's IP groups with `opens`: whether visitors from their addresses see
-all of the recording (owners). `PUT …/{gid}` opens the recording to a group that opens chosen recordings (400 for one
+all of the asset (owners). `PUT …/{gid}` opens the asset to a group that opens chosen assets (400 for one
that opens `everything` already), `DELETE …/{gid}` closes it again (404 when it wasn't open). Both answer with the list
and are audited as `recording.ip_group.open` and `recording.ip_group.close`.
@@ -558,16 +558,16 @@ PATCH /api/v1/resources/{rid}/notes/{nid}
DELETE /api/v1/resources/{rid}/notes/{nid}
```
-Notes on a recording, for people with a role in its namespace (share links and signed links don't reach them). `POST`
+Notes on an asset, for people with a role in its namespace (share links and signed links don't reach them). `POST`
with `text` (up to 5,000 characters) and, for a note about a moment, `t0` and `t1` (ms from the start; `t1` defaults
to `t0` and stops at the end of the recording) and the `quote` picked in the transcript (up to 1,000 characters);
-without `t0` the note is about the whole recording. Anyone who can read the recording can write notes, up to 500 each
-on a recording. A note is its writer's: only they see it, unless they share it (`shared: true`, which needs editor
-access) with everyone who can read the recording. `GET` lists yours and the shared ones: notes about the whole
-recording first, then by moment, each with its writer (`created_by`, `created_by_name`), `mine`, `can_delete` and
+without `t0` the note is about the whole asset. Anyone who can read the asset can write notes, up to 500 each
+on an asset. A note is its writer's: only they see it, unless they share it (`shared: true`, which needs editor
+access) with everyone who can read the asset. `GET` lists yours and the shared ones: notes about the whole
+asset first, then by moment, each with its writer (`created_by`, `created_by_name`), `mine`, `can_delete` and
`edited_at` (when its text last changed). Only its writer changes a note (`PATCH` with `text` or `shared`); its writer,
or an owner of the namespace for a shared one, deletes it. Sharing, unsharing and deleting a shared note are audited
-(`note.share`, `note.unshare`, `note.delete`, on the recording). Notes move with their recording and go when it's
+(`note.share`, `note.unshare`, `note.delete`, on the asset). Notes move with their asset and go when it's
deleted.
## notebook
@@ -588,7 +588,7 @@ GET /api/v1/notes/{pid}/blobs
DELETE /api/v1/notes/{pid}/files
```
-Note pages ([Notes](notes.md)), apart from the notes on a recording above. `GET /notes?ns=` is a namespace's page tree
+Note pages ([Notes](notes.md)), apart from the notes on an asset above. `GET /notes?ns=` is a namespace's page tree
(`all=true` adds the pages of things). `move` puts a free note inside `parent` before `before`, `history` lists what the
page was before each change, and `restore` puts an earlier version back (what it was becomes a version too). `files`
lists the files and images attached to a page; `blobs` uploads (in chunks) and reads them, and `DELETE …/files?key=`
@@ -689,7 +689,7 @@ POST /api/v1/import/web/links
`POST /import` queues the namespace's pipeline after the import, or the saved pipeline named by `pipeline` (any of
`GET /pipelines`; 400 for one that doesn't exist, before anything is saved). Every import takes a `collection` of the
-namespace to put the recordings in (default: its default collection; 404 for one of another namespace): `POST /import`,
+namespace to put the assets in (default: its default collection; 404 for one of another namespace): `POST /import`,
`POST /import/source`, `POST /uploads` and `POST /import/iiif`.
`POST /api/v1/import/source {source, paths, namespace, pipeline?, collection?, documents_as?}` imports chosen files of
@@ -698,7 +698,7 @@ a storage source now, rather than watching their folder (admins, like sources; u
pipeline, or `pipeline`; transcripts are imported. A PDF, Word, text or Markdown file is a document unless
`documents_as` is `transcript` (its text only), or the server can't make a PDF of it. Each path gets a result: `queued` (with `recording` and `job`), `already` (the namespace has it from this
source), `skipped` (a folder, or not audio, video, a document, an image or a transcript) or `error`. Choosing a file
-whose recording was deleted brings it back. Audited as `import.source`.
+whose asset was deleted brings it back. Audited as `import.source`.
### Web pages
@@ -772,7 +772,7 @@ Pushing needs only the token, as `Authorization: Bearer ` (or in the addr
a URL; the address form ends up in proxy logs, so prefer the header). Three ways to send:
- **A file as the raw body**, named by `?filename=`, `Content-Disposition` or `X-Filename`. Audio, video, documents
- and images become recordings and resources exactly as [uploads](#uploads) do, duplicates included; `.srt`, `.vtt`,
+ and images become assets exactly as [uploads](#uploads) do, duplicates included; `.srt`, `.vtt`,
`.json`, `.jsonl` and `.ics` are imported as transcripts.
- **Multipart form files** (field `file`, up to 20), with optional `title`, `url` and `text` fields.
- **JSON** `{url?, text?, title?}`: a web page or PDF kept as a document, as [web pages](#web-pages) are (a page needs
@@ -808,30 +808,30 @@ DELETE /api/v1/uploads/{uid}
`POST /import` (`server.max_upload_mb`).
`POST /uploads {namespace, filename, size, title?, modified?, pipeline?, collection?, recording?}` starts one (editors of the namespace; admins
-may name a new namespace, created when the upload finishes). With `recording`, a transcript-only recording, the file
-becomes that recording's audio instead of a recording of its own (editors of its namespace; `namespace` can then be left
+may name a new namespace, created when the upload finishes). With `recording`, a transcript-only asset, the file
+becomes that asset's audio instead of an asset of its own (editors of its namespace; `namespace` can then be left
out; 409 when it has audio already; 400 for anything but audio or video). [Processing](processing.md#importing-transcripts) says what runs then. `pipeline`
-runs instead of the namespace's once a new recording is made, and `collection` is where it goes (neither with
+runs instead of the namespace's once a new asset is made, and `collection` is where it goes (neither with
`recording`, which stays in its collection). The name loses any folders and its extension is lowercased; `modified`
-(the file's last-modified time in milliseconds) dates the recording when its name doesn't. 400 for a type not in
+(the file's last-modified time in milliseconds) dates the asset when its name doesn't. 400 for a type not in
`uploads.extensions`, 413 over `uploads.max_mb`, 507 when the server's disk can't hold it with 512 MB to spare.
`PUT /uploads/{uid}?offset=` sends the next piece as the raw request body (`application/octet-stream`), starting at
`offset`: the upload's `offset` is how many bytes have arrived. Pieces stream to a partial file under
`data_dir/uploads/.partial`; a piece that breaks off is dropped whole, so after a dropped connection the client gets the
upload and sends from its `offset`. 409 when `offset` isn't where the upload has got to, or while another piece of it
-is arriving. The piece with the last byte moves the file to `data_dir/uploads///`, makes it a
-recording and queues the namespace's pipeline (or attaches it, adding the steps that need media to the recording's job):
+is arriving. The piece with the last byte moves the file to `data_dir/uploads///`, makes it an
+asset and queues the namespace's pipeline (or attaches it, adding the steps that need media to the asset's job):
the answer has `state: "done"`, `recording` and `job`. When the namespace
-already has the same file (uploaded, scanned or imported before), no second recording is made: `duplicate` is true and
+already has the same file (uploaded, scanned or imported before), no second asset is made: `duplicate` is true and
`recording` is that one, which gets its media back if it had lost it. Audited as `upload` (with `attached` in the
detail). Sending the last piece again
answers the same.
`GET /uploads` lists your unfinished uploads, newest first: choosing the same file for the same namespace again carries
on from its `offset`. Only the person uploading (and admins) can see, send to or `DELETE` an upload; `DELETE` throws away
-what arrived. An upload nobody has sent a piece to for `uploads.expire_hours` is removed with its partial file. Deleting a
-recording later leaves its uploaded file in place, like any other media file.
+what arrived. An upload nobody has sent a piece to for `uploads.expire_hours` is removed with its partial file. Deleting an
+asset later leaves its uploaded file in place, like any other media file.
## search
@@ -846,11 +846,11 @@ GET /api/v1/mentions
supplementary transcripts, captions, translations and indexes, or in what a model said its shots and pages show) in the
namespaces you can read, best first: every word
(English stemming), "quoted phrases" as written, `OR` between alternatives; `ns`, `speaker`, `emotion` and `recording`
-narrow it, and `object` keeps to the recordings a kind of object is seen in ([Objects](#objects));
+narrow it, and `object` keeps to the assets a kind of object is seen in ([Objects](#objects));
`limit`/`offset` page through it. `total` counts the moments ranked so far (`capped` when there may be more).
With `facets=true` it also counts all the matching moments, whatever the page, by namespace, speaker, emotion and
-recording (`facets`: up to 50 values each, most first, and `moments`), and lists the kinds of object seen in the
-recordings they're in, with how many of those recordings each is in (`objects`); past 20,000 moments the counts cover
+asset (`facets`: up to 50 values each, most first, and `moments`), and lists the kinds of object seen in the
+assets they're in, with how many of those assets each is in (`objects`); past 20,000 moments the counts cover
20,000 of them (`partial`).
Each hit's `source` says where it was found: `said` (the transcript), `screen` (text on screen), `page` (a document's or an
@@ -869,7 +869,7 @@ matched, `semantic` whether search by meaning is set up, and `meaning` why it wa
Search has no prefix search (`interp*` looks for the word "interp"). `GET /search/terms?prefix=interp` lists whole
words said in the namespaces you can read (`ns` for one) that start with it, the most said first, with how often and
-in how many recordings (`limit`, default 8, at most 20); the web app offers them as "Try …".
+in how many assets (`limit`, default 8, at most 20); the web app offers them as "Try …".
## speakers
@@ -1066,12 +1066,12 @@ stops it taking new jobs; `drain` also hands the job it has back to the queue af
gives the jobs of each status and `namespaces` the jobs in each namespace, both over `namespace` and `batch` but any
status, so a client can show its filters' counts while one is applied.
-Every job names its recording (`title`) and the pipeline it runs with the version it pinned (`pipeline`:
+Every job names its asset (`title`) and the pipeline it runs with the version it pinned (`pipeline`:
`{id, version, name}`; `{name: "Standard"}` for the standard steps, null when the steps were chosen directly).
`GET /jobs/{jid}` adds how each step went, `step_runs` (one per step, null until it runs): `started_at`, `finished_at`,
`seconds`, `outcome` (`running`, `done`, `skipped`, `failed`), `note` (its last message, why it skipped, or its error),
`worker`, `log_from`/`log_to` (its lines of the whole log) and `outputs` (`[{key, template, version, model}]`, saved as
-`outputs.`). It also adds `estimates`, how long each step usually takes on this recording in seconds (from the
+`outputs.`). It also adds `estimates`, how long each step usually takes on this asset in seconds (from the
last 25 runs of that step or template; null with none), and while the job is queued or running `eta_seconds`.
A run keeps its whole log (up to 100,000 lines); the job itself carries its last 200 lines (`log`) and how many there
@@ -1101,7 +1101,7 @@ DELETE /api/v1/watches/{wid}
POST /api/v1/watches/{wid}/scan
```
-`GET /sources/{sid}/browse?path=` lists a folder of a source; each file says which recordings it is already
+`GET /sources/{sid}/browse?path=` lists a folder of a source; each file says which assets it is already
(`imported: [{recording, namespace}]`).
A watched folder's `kinds` says what it picks up: `audio` (and video), `transcripts`, `both` of those, `documents`
@@ -1162,8 +1162,8 @@ conversation. A conversation titled after the first question is retitled when th
A conversation's `scope` narrows what it draws on: `namespaces`, `recordings`, `collections`, `speakers`, `from` and
`to`; every key narrows it further, and an empty scope is everything you can read. `collections` are ids of
-collections you can see (yours or shared); the conversation draws on their recordings as they are each time it
-answers, so a filter collection's new recordings count, and a deleted collection adds none.
+collections you can see (yours or shared); the conversation draws on their assets as they are each time it
+answers, so a filter collection's new assets count, and a deleted collection adds none.
`GET /chats/{cid}` returns each answer with the `steps` the assistant took (`{tool, args, summary}`), its `notice` and
`error`, and its latest source `check` (`{claims, supported, verdicts, uncited}`), as they were when it was written
@@ -1171,8 +1171,8 @@ or checked.
## collections
-Saved collections: lists of recordings from anywhere, to chat with or run batches on. A namespace's own collections,
-which recordings live in, are under [namespaces](#collections-of-a-namespace).
+Saved collections: lists of assets from anywhere, to chat with or run batches on. A namespace's own collections,
+which assets live in, are under [namespaces](#collections-of-a-namespace).
```
GET /api/v1/collections
@@ -1250,27 +1250,27 @@ POST /api/v1/public/recordings/{rid}/request
GET /api/v1/access-requests
```
-`GET /public/home` lists the featured public recordings (for everyone, members too) and the collections the caller
-sees anything in, with how many of their recordings they see (`network` names the IP group that opens all of one to
+`GET /public/home` lists the featured public assets (for everyone, members too) and the collections the caller
+sees anything in, with how many of their assets they see (`network` names the IP group that opens all of one to
the caller's address). `GET /public/collections/{name}` is a collection's page:
-the namespace's description and the recordings the caller sees there, newest first (`limit`, `offset`, and `total` on
-all pages). Each recording is a card with the caller's `view` of it; `locked` cards carry the title only. A poster
+the namespace's description and the assets the caller sees there, newest first (`limit`, `offset`, and `total` on
+all pages). Each asset is a card with the caller's `view` of it; `locked` cards carry the title only. A poster
frame comes only with media the caller may play. A collection with nothing for the caller answers 404.
-`GET /public/search?q=` (`limit`, `offset`) finds the recordings the caller sees by their title, and by the lines of
+`GET /public/search?q=` (`limit`, `offset`) finds the assets the caller sees by their title, and by the lines of
the transcripts they may read (the same query syntax as `/search`: words, "phrases", OR). Title matches come first;
each result is a card with up to three matching `hits` (`t0` and an HTML-escaped `snippet` with ``, and the
-`page` of a document's text). Restricted recordings and closed transcripts match on the title only.
+`page` of a document's text). Restricted assets and closed transcripts match on the title only.
-`GET /public/recordings/{rid}` is a recording's public page as the caller may see it. `view` says how:
+`GET /public/recordings/{rid}` is an asset's public page as the caller may see it. `view` says how:
* `full`: the caller has permission, so all of it: a role in its namespace (admins have every role; `member` is
- true), permission given on the recording (`granted`), or an address in an IP group that opens it (`network`, the
+ true), permission given on the asset (`granted`), or an address in an IP group that opens it (`network`, the
group's name).
-* `public`: a public recording, for everyone else: its description (the metadata IIIF publishes) and only its open
+* `public`: a public asset, for everyone else: its description (the metadata IIIF publishes) and only its open
parts: `media` (a signed link to the audio or video, with its waveform), `transcript` (speakers and lines, and the
transcript files to download when the transcript is open to everyone) and `chapters` (the index).
-* `locked`: a restricted recording, for someone signed in without permission: its title and namespace only.
+* `locked`: a restricted asset, for someone signed in without permission: its title and namespace only.
A document's or an image's media are its pages and its file: `media.kind` is `document` or `image`, `media.pages`
lists each page (`idx`, `width`, `height`, `label`, and signed links to its `image` and `thumb`), `media.url` is the
@@ -1283,5 +1283,5 @@ many more there are. For someone signed in without permission,
`can_request` says whether they may ask for access (something is closed to them) and `request` is their latest request.
`POST …/request` with an optional `message` asks the owners (400 when the caller already sees all of it, or when all of
it is open to everyone); asking again replaces the request. `GET /access-requests` lists the requests waiting for an
-answer in the namespaces the caller owns. Recordings the caller may not see at all (restricted ones
+answer in the namespaces the caller owns. Assets the caller may not see at all (restricted ones
to visitors who aren't signed in, private ones to anyone without permission) answer 404, as missing ones do.
diff --git a/docs/architecture.md b/docs/architecture.md
index 45c6cf48d..c4a93e173 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -17,7 +17,7 @@ processes around one database, with word search in a small index beside it:
| **Next.js** (`nextjs-frontend/`) | The web app. Auth.js (NextAuth v5) keeps the session; server components and server actions call the API with the session's access token through the generated, typed client. |
| **FastAPI** (`fastapi_backend/app/`) | The HTTP API under `/api/v1`, IIIF endpoints under `/iiif`, the embeddable player at `/embed/` (and `/s/`, a share link's short address) and stored reports at `/reports/...`. |
| **Workers** (`lens worker`) | Run queued jobs: transcription, diarisation, video analysis, entity extraction, LLM steps and reports. Any number, on any machine that reaches the database; each can be limited to the steps it can run (for example mlx transcription on a Mac). |
-| **SurrealDB** | Everything but the word index: recordings, transcripts, speakers, the knowledge graph (as graph edges), jobs, accounts and settings. |
+| **SurrealDB** | Everything but the word index: assets, transcripts, speakers, the knowledge graph (as graph edges), jobs, accounts and settings. |
| **Word index** | Full-text search. By default a SQLite FTS5 file in `/search/` (BM25 ranking, stemming, highlights); `search.engine: opensearch` moves it to an OpenSearch cluster. It is kept in step with SurrealDB from a change table before each search (`app/domain/textindex.py`). |
## Backend layout
@@ -33,7 +33,7 @@ fastapi_backend/
security.py access tokens (JWT) and signed media links
middleware.py allowed hosts, security headers, IIIF CORS
api/
- deps.py Db, Cfg, CurrentUser, Writer, Admin*, Acl (namespace/recording access)
+ deps.py Db, Cfg, CurrentUser, Writer, Admin*, Acl (namespace/asset access)
media.py signs media links in responses
streaming.py byte-range responses for audio and video
v1/router.py every /api/v1 router, one module per area in v1/routes/
@@ -70,7 +70,7 @@ saved in the app by admins. See [Configuration](configuration.md).
Admins can do everything. Everyone else has a role per namespace: **viewer** (read, listen, search, chat), **editor**
(import, correct, rename and merge speakers, run pipelines) or **owner** (members and namespace settings). A namespace
-you have no role in behaves as if it didn't exist: its recordings, search hits, graph nodes and reports all answer 404.
+you have no role in behaves as if it didn't exist: its assets, search hits, graph nodes and reports all answer 404.
`deps.Access` enforces this on every request. See [Authentication](authentication.md).
## Background work
@@ -89,11 +89,11 @@ run a separate `worker` service.
Audio, video, frames, the pages of documents and images, and word clouds are loaded by `
"
f''
)
elif not passwords: # auth.passwords off: this page has no passkey sign-in yet, so there is nothing to submit
body = (
- f"
Sign in to {esc(site)}
The viewer at {esc(origin or 'another site')} wants to play recordings that need an account.
"
+ f"
Sign in to {esc(site)}
The viewer at {esc(origin or 'another site')} wants to open assets that need an account.
"
+ (f'
{esc(error)}
' if error else "")
+ f"
{esc(site)} signs people in with a passkey only, and this page can't use passkeys yet, so this viewer "
"can only play what is open to everyone.
"
)
else:
body = (
- f"
Sign in to {esc(site)}
The viewer at {esc(origin or 'another site')} wants to play recordings that need an account.
"
+ f"
Sign in to {esc(site)}
The viewer at {esc(origin or 'another site')} wants to open assets that need an account.