Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

Clarify browser speech provider connection failures

tianma-if2c4f8b48243b
diff --git a/apps/web/src/components/EditorPane.tsx b/apps/web/src/components/EditorPane.tsx
index 3938137d..31edfbe8 100644
--- a/apps/web/src/components/EditorPane.tsx
+++ b/apps/web/src/components/EditorPane.tsx
@@ -104,6 +104,7 @@ import { RevisionHistoryDialog } from "./dialogs/RevisionHistoryDialog";
import { ExternalLinkDialog } from "./dialogs/ExternalLinkDialog";
import { MathFormulaDialog } from "./dialogs/MathFormulaDialog";
import { AttachmentTranscriptDialog } from "./dialogs/AttachmentTranscriptDialog";
+import { SpeechProviderReachabilityError } from "@/lib/speech-transcription-error";
import { EditorBlockDragHandle } from "./editor/EditorBlockDragHandle";
import {
applyMathFormula,
@@ -3153,7 +3154,10 @@ const RichEditorPane = ({
} catch (error) {
if (attachmentTranscriptAbortRef.current !== controller || controller.signal.aborted) return;
setAttachmentTranscript((current) => current?.memoId === currentMemoId && current.filename === target.filename
- ? { ...current, loading: false, error: error instanceof Error ? error.message : t("speechTranscription.recognizeFailed") }
+ ? { ...current, loading: false, error: error instanceof SpeechProviderReachabilityError
+ ? t(error.platform === "browser"
+ ? "speechTranscription.browserDirectUnavailable" : "speechTranscription.desktopDirectUnavailable")
+ : error instanceof Error ? error.message : t("speechTranscription.recognizeFailed") }
: current);
} finally {
if (attachmentTranscriptAbortRef.current === controller) attachmentTranscriptAbortRef.current = null;
diff --git a/apps/web/src/components/settings/SpeechProviderCard.tsx b/apps/web/src/components/settings/SpeechProviderCard.tsx
index 3bca6b7e..6711fa4d 100644
--- a/apps/web/src/components/settings/SpeechProviderCard.tsx
+++ b/apps/web/src/components/settings/SpeechProviderCard.tsx
@@ -24,6 +24,7 @@ import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@
import { Switch } from "@/components/ui/switch";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
import { api } from "@/lib/api";
+import { SpeechProviderReachabilityError } from "@/lib/speech-transcription-error";
export const SpeechProviderCard = ({
provider: saved,
@@ -322,7 +323,10 @@ export const SpeechProviderCard = ({
) : null}
{testMutation.isError ? (
<p className="text-xs font-medium text-rose-600" role="alert">
- {aiErrorMessage(testMutation.error, t("speechTranscription.testFailed"), t("aiModel.encryptionKeyMissing"), t("speechTranscription.savedCredentialsUnavailable"))}
+ {testMutation.error instanceof SpeechProviderReachabilityError
+ ? t(testMutation.error.platform === "browser"
+ ? "speechTranscription.browserDirectUnavailable" : "speechTranscription.desktopDirectUnavailable")
+ : aiErrorMessage(testMutation.error, t("speechTranscription.testFailed"), t("aiModel.encryptionKeyMissing"), t("speechTranscription.savedCredentialsUnavailable"))}
</p>
) : null}
{saveMutation.isError ? (
diff --git a/apps/web/src/components/settings/SpeechTranscriptionCard.tsx b/apps/web/src/components/settings/SpeechTranscriptionCard.tsx
index c159d6ce..03cd8d3a 100644
--- a/apps/web/src/components/settings/SpeechTranscriptionCard.tsx
+++ b/apps/web/src/components/settings/SpeechTranscriptionCard.tsx
@@ -18,6 +18,7 @@ import { Input } from "@/components/ui/input";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select";
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
import { api } from "@/lib/api";
+import { SpeechProviderReachabilityError } from "@/lib/speech-transcription-error";
import {
SETTINGS_CARD_HEADER_CLASSNAME,
SETTINGS_CARD_ICON_CLASSNAME,
@@ -242,7 +243,10 @@ export const SpeechTranscriptionCard = ({ demoMode }: { demoMode: boolean }) =>
) : null}
{testMutation.isError ? (
<p className="text-xs font-medium text-rose-600" role="alert">
- {aiErrorMessage(testMutation.error, t("speechTranscription.testFailed"), t("aiModel.encryptionKeyMissing"), t("speechTranscription.savedCredentialsUnavailable"))}
+ {testMutation.error instanceof SpeechProviderReachabilityError
+ ? t(testMutation.error.platform === "browser"
+ ? "speechTranscription.browserDirectUnavailable" : "speechTranscription.desktopDirectUnavailable")
+ : aiErrorMessage(testMutation.error, t("speechTranscription.testFailed"), t("aiModel.encryptionKeyMissing"), t("speechTranscription.savedCredentialsUnavailable"))}
</p>
) : null}
{createMutation.isError ? (
diff --git a/apps/web/src/lib/speech-transcription-error.ts b/apps/web/src/lib/speech-transcription-error.ts
new file mode 100644
index 00000000..17967b82
--- /dev/null
+++ b/apps/web/src/lib/speech-transcription-error.ts
@@ -0,0 +1,8 @@
+export class SpeechProviderReachabilityError extends Error {
+ readonly code = "speech_provider_direct_unreachable";
+
+ constructor(readonly platform: "browser" | "desktop") {
+ super("The client could not reach the speech provider directly.");
+ this.name = "SpeechProviderReachabilityError";
+ }
+}
diff --git a/apps/web/src/lib/transcribe-note-resource.test.mjs b/apps/web/src/lib/transcribe-note-resource.test.mjs
index fc61acf9..cb509d32 100644
--- a/apps/web/src/lib/transcribe-note-resource.test.mjs
+++ b/apps/web/src/lib/transcribe-note-resource.test.mjs
@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
import { fileURLToPath } from "node:url";
import { ALL_FORMATS, BufferSource, Input } from "mediabunny";
import { extractAudioParts, testSpeechService, transcribePreparedAudioParts } from "./transcribe-note-resource.ts";
+import { SpeechProviderReachabilityError } from "./speech-transcription-error.ts";
const fixturePath = fileURLToPath(new URL("./fixtures/transcription-video.mp4", import.meta.url));
@@ -84,6 +85,19 @@ describe("client-side note media preparation", () => {
expect(requests[1].init.body.get("model")).toBe("whisper-1");
});
+ test("a browser transport failure does not claim the token or model is invalid", async () => {
+ async function* parts() { yield new File(["audio"], "sample.mp3", { type: "audio/mpeg" }); }
+ await expect(transcribePreparedAudioParts(
+ { baseUrl: "https://speech.example/v1", modelId: "whisper-1", apiKey: "test-token" },
+ parts(),
+ async () => { throw new TypeError("Failed to fetch"); },
+ )).rejects.toMatchObject({
+ code: "speech_provider_direct_unreachable",
+ platform: "browser",
+ });
+ expect(new SpeechProviderReachabilityError("browser").message).not.toMatch(/token|model/i);
+ });
+
test("sends each prepared segment directly to the configured speech endpoint", async () => {
const requests = [];
const completed = [];
diff --git a/apps/web/src/lib/transcribe-note-resource.ts b/apps/web/src/lib/transcribe-note-resource.ts
index ff214729..0bc4f6c0 100644
--- a/apps/web/src/lib/transcribe-note-resource.ts
+++ b/apps/web/src/lib/transcribe-note-resource.ts
@@ -16,6 +16,7 @@ import {
type OutputFormat,
} from "mediabunny";
import { api, directProviderFetch } from "./api";
+import { SpeechProviderReachabilityError } from "./speech-transcription-error";
const MAX_SOURCE_BYTES = 1024 * 1024 * 1024;
const MAX_PROVIDER_FILE_BYTES = 24_000_000;
@@ -196,9 +197,9 @@ export async function transcribePreparedAudioParts(
});
} catch {
if (signal?.aborted) signal.throwIfAborted();
- throw new Error(typeof window !== "undefined" && window.edgeeverDesktop?.isAvailable
- ? "Could not reach the speech provider directly. Check the provider URL and network connection."
- : "Could not reach the speech provider directly. Check its browser CORS policy or network connection.");
+ throw new SpeechProviderReachabilityError(
+ typeof window !== "undefined" && window.edgeeverDesktop?.isAvailable ? "desktop" : "browser",
+ );
}
if (!response.ok) throw new Error(`The speech provider returned HTTP ${response.status}.`);
const result = await response.json().catch(() => null) as { text?: unknown } | null;
diff --git a/docs/video-clip-spec.md b/docs/video-clip-spec.md
index a54e8827..16ce71dd 100644
--- a/docs/video-clip-spec.md
+++ b/docs/video-clip-spec.md
@@ -10,6 +10,9 @@ Users can explicitly transcribe an audio or MP4/WebM video attachment already up
When adding a service, users can test the unsaved URL, model ID, and token. When editing, they can select an existing model and test with either the stored token or a replacement. The current client sends a short bundled speech sample directly to the model service and shows its returned transcript. Testing does not save the form and may incur a small provider charge. Browser CORS limitations are the same as for normal transcription.
+When a browser cannot establish a direct connection, the client can only report an incomplete check; this does not establish that the token, model, or speech endpoint is invalid. If the provider blocks cross-origin requests, test in the desktop app. Do not relay the transcription request through the instance merely to make the browser test pass.
+"OpenAI-compatible" describes an API shape and does not guarantee that the provider implements `/audio/transcriptions`. Once the desktop app avoids the browser CORS restriction, a real short-speech request is still needed to verify that endpoint and the selected model.
+
## Withdrawn external media retrieval design: technical notes
The following records an unreleased external media retrieval design for possible future evaluation of authorized use. **It does not describe current product behavior or a planned feature.** The withdrawn scope includes external audio retrieval, browser session reuse, automatic yt-dlp installation and updates, external video transcription jobs, and desktop polling. Note attachment transcription above is a separate implementation.
diff --git a/docs/video-clip-spec.zh-CN.md b/docs/video-clip-spec.zh-CN.md
index 1270edde..9a4f01ef 100644
--- a/docs/video-clip-spec.zh-CN.md
+++ b/docs/video-clip-spec.zh-CN.md
@@ -10,6 +10,9 @@
添加服务时可用尚未保存的地址、模型 ID 和 Token 测试连接;编辑服务时可选择已添加的模型,并沿用已保存的 Token 或输入新 Token 测试。测试从当前客户端直连模型服务,发送一段内置短语音并显示返回的文本;测试不保存表单,可能产生少量模型费用。浏览器跨域限制与真实转录相同。
+浏览器无法建立直连时,客户端只能报告连接未完成,不能据此判断 Token、模型或语音接口无效。服务商不允许跨域请求时,应在桌面客户端测试;不得为通过 Web 测试而改由实例转发识别请求。
+“OpenAI 兼容”只说明接口形状,不能保证服务商提供 `/audio/transcriptions`;桌面端绕开浏览器跨域限制后,仍须通过真实短语音请求验证该接口及所选模型。
+
## 已撤回的外部媒体抓取方案:技术备忘
以下记录未上线的外部媒体抓取设计,供以后评估授权场景时参考,**不是当前产品行为或待实现需求**。撤回范围包括外部音轨抓取、浏览器登录状态复用、yt-dlp 自动安装与更新、外部视频识别任务和桌面轮询。上面的笔记附件语音识别是独立实现。
diff --git a/packages/shared/src/i18n/en-US.ts b/packages/shared/src/i18n/en-US.ts
index 02d86fee..16267d59 100644
--- a/packages/shared/src/i18n/en-US.ts
+++ b/packages/shared/src/i18n/en-US.ts
@@ -1173,7 +1173,7 @@ export const enUS = {
title: "Speech recognition model settings",
baseUrl: "Endpoint URL",
baseUrlPlaceholder: "https://api.example.com/v1",
- baseUrlHint: "Requests go to /audio/transcriptions under this URL.",
+ baseUrlHint: "Requests go to /audio/transcriptions under this URL; the provider must actually support this speech endpoint.",
modelId: "Model ID",
modelIdPlaceholder: "whisper-1",
apiToken: "API token",
@@ -1207,6 +1207,8 @@ export const enUS = {
testHint: "A short built-in audio sample is sent directly from this client to the model service. This may incur a small provider charge. Testing does not save the form.",
testSucceeded: "Connection works. Transcript: “{{transcript}}”",
testFailed: "Speech service test failed.",
+ browserDirectUnavailable: "This browser could not connect directly to the speech service. The provider may block cross-origin requests (CORS), or the network may be unavailable. The token and model have not been verified. Test in the desktop app or use a provider that allows browser requests.",
+ desktopDirectUnavailable: "The desktop app could not connect directly to the speech service. Check the endpoint and network connection; the token and model have not been verified.",
removeModel: "Remove model",
noModels: "No models yet",
deleteProviderConfirm: "Delete the speech service “{{name}}”? Its saved token is deleted too.",
diff --git a/packages/shared/src/i18n/ja.ts b/packages/shared/src/i18n/ja.ts
index 26655a19..05e24716 100644
--- a/packages/shared/src/i18n/ja.ts
+++ b/packages/shared/src/i18n/ja.ts
@@ -1173,7 +1173,7 @@ export const ja = {
title: "音声認識モデル設定",
baseUrl: "エンドポイント URL",
baseUrlPlaceholder: "https://api.example.com/v1",
- baseUrlHint: "リクエストはこの URL 配下の /audio/transcriptions に送られます。",
+ baseUrlHint: "リクエストはこの URL 配下の /audio/transcriptions に送られます。提供元がこの音声 API に実際に対応している必要があります。",
modelId: "モデル ID",
modelIdPlaceholder: "whisper-1",
apiToken: "API トークン",
@@ -1207,6 +1207,8 @@ export const ja = {
testHint: "短い内蔵音声をこのクライアントからモデルサービスへ直接送信します。少額の利用料金が発生する場合があります。テストでは設定を保存しません。",
testSucceeded: "接続できました。文字起こし結果:「{{transcript}}」",
testFailed: "音声サービスのテストに失敗しました。",
+ browserDirectUnavailable: "このブラウザーから音声サービスに直接接続できません。提供元が CORS を許可していないか、ネットワークに問題がある可能性があります。トークンとモデルの有効性は未確認です。デスクトップアプリでテストするか、ブラウザーからの接続を許可するサービスを使用してください。",
+ desktopDirectUnavailable: "デスクトップアプリから音声サービスに直接接続できません。エンドポイントとネットワークを確認してください。トークンとモデルの有効性は未確認です。",
removeModel: "モデルを削除",
noModels: "モデルはまだありません",
deleteProviderConfirm: "音声サービス「{{name}}」を削除しますか?保存したトークンも削除されます。",
diff --git a/packages/shared/src/i18n/pl.ts b/packages/shared/src/i18n/pl.ts
index c03ad9dd..5101ffe5 100644
--- a/packages/shared/src/i18n/pl.ts
+++ b/packages/shared/src/i18n/pl.ts
@@ -1173,7 +1173,7 @@ export const pl = {
title: "Ustawienia modeli rozpoznawania mowy",
baseUrl: "Adres interfejsu",
baseUrlPlaceholder: "https://api.example.com/v1",
- baseUrlHint: "Żądanie trafia na /audio/transcriptions pod tym adresem.",
+ baseUrlHint: "Żądanie trafia na /audio/transcriptions pod tym adresem; dostawca musi rzeczywiście obsługiwać ten interfejs transkrypcji.",
modelId: "ID modelu",
modelIdPlaceholder: "whisper-1",
apiToken: "Token API",
@@ -1207,6 +1207,8 @@ export const pl = {
testHint: "Krótka wbudowana próbka audio jest wysyłana bezpośrednio z tego klienta do usługi modelu. Może to spowodować niewielki koszt. Test nie zapisuje formularza.",
testSucceeded: "Połączenie działa. Transkrypcja: „{{transcript}}”",
testFailed: "Test usługi rozpoznawania mowy nie powiódł się.",
+ browserDirectUnavailable: "Ta przeglądarka nie może połączyć się bezpośrednio z usługą rozpoznawania mowy. Dostawca może blokować żądania CORS lub wystąpił problem z siecią. Token i model nie zostały zweryfikowane. Przetestuj połączenie w aplikacji komputerowej albo użyj usługi obsługującej żądania z przeglądarki.",
+ desktopDirectUnavailable: "Aplikacja komputerowa nie może połączyć się bezpośrednio z usługą rozpoznawania mowy. Sprawdź adres usługi i połączenie sieciowe; token i model nie zostały zweryfikowane.",
removeModel: "Usuń model",
noModels: "Nie ma jeszcze modeli",
deleteProviderConfirm: "Usunąć usługę mowy „{{name}}”? Zapisany token też zostanie usunięty.",
diff --git a/packages/shared/src/i18n/zh-CN.ts b/packages/shared/src/i18n/zh-CN.ts
index 1a77bd59..b596647e 100644
--- a/packages/shared/src/i18n/zh-CN.ts
+++ b/packages/shared/src/i18n/zh-CN.ts
@@ -1173,7 +1173,7 @@ export const zhCN = {
title: "语音识别模型配置",
baseUrl: "接口地址",
baseUrlPlaceholder: "https://api.example.com/v1",
- baseUrlHint: "请求会发到该地址下的 /audio/transcriptions。",
+ baseUrlHint: "请求会发到该地址下的 /audio/transcriptions;服务商必须实际支持此语音接口。",
modelId: "模型 ID",
modelIdPlaceholder: "whisper-1",
apiToken: "API Token",
@@ -1207,6 +1207,8 @@ export const zhCN = {
testHint: "将从当前客户端直接发送一段内置短音频给模型服务;可能产生少量模型费用。测试不会保存表单。",
testSucceeded: "连接可用,识别结果:“{{transcript}}”",
testFailed: "语音服务测试失败。",
+ browserDirectUnavailable: "当前浏览器无法直连语音服务,可能是服务商未开放跨域访问(CORS)或网络异常。Token 和模型是否可用尚未验证;请在桌面客户端测试,或换用支持浏览器跨域访问的服务。",
+ desktopDirectUnavailable: "桌面客户端无法直连语音服务。请检查接口地址和网络连接;Token 和模型是否可用尚未验证。",
removeModel: "移除模型",
noModels: "还没有模型",
deleteProviderConfirm: "删除语音服务「{{name}}」?保存的 Token 会一起删除。",