Skip to content

Commit 49671b7

Browse files
feat(media-use): source sound effects from Openverse with the bundled library offline (#5753)
* feat(media-use): source sound effects from Openverse with the bundled library offline * docs(media-use): name the resolve credits file without a dead path * style(skills): restore the slideshow harness formatting the pinned formatter expects * fix(media-use): keep Openverse credit text to one safe line and read credits without a race * fix(media-use): Openverse sound effects record as the engine's, so a rerun writes no copy * fix(media-use): two sound effect resolves at once each keep their credit line * fix(media-use): the standalone media-use copy takes the same credit lock * fix(media-use): a sound effect credit is always one safe line with a provider link writeSfxCredit cleans the credit and source link itself, since the CLI writes credits from a saved record. Backticks, brackets, angle brackets and backslashes are stripped, and a source link must be https on an Openverse audio provider host (Freesound, Jamendo, Wikimedia Commons) or it is left out.
1 parent deeb8d4 commit 49671b7

34 files changed

Lines changed: 1175 additions & 320 deletions

‎packages/cli/src/media-use/lib/heygen-cli.mjs‎

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -102,19 +102,16 @@ const pendingFailureTracking = new Set();
102102
// API, move this state into a per-resolve context before reusing that path.
103103
let pendingRemediation = null;
104104

105-
const TOOL_WORDS = { bgm: "music", sfx: "sound-effect" };
106-
107-
/** A music or sound-effect resolve miss after the heygen CLI was missing or too old: what is missing, the host
108-
* app's own tool, the fix. Other types keep the generic miss. */
105+
/** A music resolve miss after the heygen CLI was missing or too old: what is missing, the host app's own
106+
* tool, the fix. Other types keep the generic miss. */
109107
export function heygenMiss(type, { code }) {
110-
const tool = TOOL_WORDS[type];
111-
if (!tool) return null;
108+
if (type !== "bgm") return null;
112109
const outdated = code === "outdated";
113110
const state = outdated ? `older than v${HEYGEN_MIN_VERSION}` : "not installed";
114111
return {
115112
code: outdated ? "heygen_cli_outdated" : "heygen_cli_missing",
116113
fix: outdated ? HEYGEN_UPDATE_COMMAND : HEYGEN_INSTALL_COMMAND,
117-
error: `${type} needs the heygen CLI, which is ${state}: use your host app's own ${tool} tool if it has one, or ${outdated ? "update" : "install"} the CLI.`,
114+
error: `${type} needs the heygen CLI, which is ${state}: use your host app's own music tool if it has one, or ${outdated ? "update" : "install"} the CLI.`,
118115
};
119116
}
120117

‎packages/cli/src/media-use/lib/heygen-cli.test.mjs‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -301,13 +301,13 @@ test("flushHeygenFailureTracking resolves immediately when nothing is pending",
301301
await flushHeygenFailureTracking();
302302
});
303303

304-
test("only a music or sound-effect miss names the heygen CLI and the host app's own tool", () => {
305-
for (const type of ["image", "icon", "voice", "video"])
304+
test("only a music miss names the heygen CLI and the host app's own tool", () => {
305+
for (const type of ["sfx", "image", "icon", "voice", "video"])
306306
assert.equal(heygenMiss(type, { code: "not_found" }), null, type);
307307
assert.equal(heygenMiss("bgm", { code: "not_found" }).code, "heygen_cli_missing");
308-
const sfx = heygenMiss("sfx", { code: "outdated" });
309-
assert.equal(sfx.code, "heygen_cli_outdated");
310-
assert.match(sfx.error, /host app's own sound-effect tool/);
308+
const bgm = heygenMiss("bgm", { code: "outdated" });
309+
assert.equal(bgm.code, "heygen_cli_outdated");
310+
assert.match(bgm.error, /host app's own music tool/);
311311
});
312312

313313
test("a CLI that rejects --headers without printing a version is outdated", () => {

‎packages/cli/src/media-use/lib/manifest.d.mts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ export function allocateId(
1111
type: string,
1212
ext: string,
1313
): Omit<Reservation, "fullPath">;
14+
export function withMediaLock<T>(projectDir: string, fn: () => T): T;
1415
export function withReservedFileSync<T>(
1516
projectDir: string,
1617
type: string,

‎packages/cli/src/media-use/lib/manifest.mjs‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -107,8 +107,7 @@ export function recordInPlace(
107107
description: description || basename(path),
108108
...(duration != null && { duration: Math.round(duration * 10) / 10 }),
109109
};
110-
mkdirSync(mediaDir(projectDir), { recursive: true });
111-
return withLock(mediaDir(projectDir), () => {
110+
return withMediaLock(projectDir, () => {
112111
const latest = latestRecordFor(projectDir, path);
113112
const same = ["source", "description", "duration"].every(
114113
(key) => latest?.[key] === fields[key],
@@ -203,17 +202,21 @@ function withLock(dir, fn) {
203202
}
204203
}
205204

205+
/** Runs `fn` holding the project's `.media/.lock`, so concurrent resolves take turns on what it guards. */
206+
export function withMediaLock(projectDir, fn) {
207+
mkdirSync(mediaDir(projectDir), { recursive: true });
208+
return withLock(mediaDir(projectDir), fn);
209+
}
210+
206211
// Atomically allocate the next free id for `type` AND reserve it on disk, so a
207212
// slow download/copy between allocation and appendRecord can't let a concurrent
208213
// caller grab the same id (the MU-23 clobber). Under the lock we take the max id
209214
// across BOTH the manifest and any already-reserved files in the type dir, then
210215
// O_EXCL-create an empty marker under core's atomic temp name, which Studio's
211216
// project history skips. Returns { id, localPath, markerPath }.
212217
export function allocateId(projectDir, type, ext) {
213-
mkdirSync(mediaDir(projectDir), { recursive: true });
214-
const typeDir = typeDirPath(projectDir, type);
215-
mkdirSync(typeDir, { recursive: true });
216-
return withLock(mediaDir(projectDir), () => {
218+
mkdirSync(typeDirPath(projectDir, type), { recursive: true });
219+
return withMediaLock(projectDir, () => {
217220
const id = nextFreeId(projectDir, type);
218221
const localPath = `.media/${typeSubdir(type)}/${id}${ext}`;
219222
// Same shape as core atomicTempPath: an empty file at the final name would be committed.
Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
// Sound effects from Openverse (https://api.openverse.org): free, no key.
2+
// Anonymous use is rate limited (20 requests a minute, 200 a day); callers fall
3+
// back to the bundled library when it is unavailable.
4+
5+
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
6+
import { dirname } from "node:path";
7+
8+
const OPENVERSE_AUDIO_URL = "https://api.openverse.org/v1/audio/";
9+
// The only licences media-use accepts: no NonCommercial, ShareAlike or NoDerivatives.
10+
export const OPENVERSE_SFX_LICENSES = new Set(["cc0", "by"]);
11+
const PLAYABLE_FILETYPES = new Set(["mp3", "wav", "ogg", "flac"]);
12+
const MAX_SFX_MS = 15000;
13+
const IDEAL_SFX_MS = 4000;
14+
const BY_PENALTY = 2;
15+
const SEARCH_TIMEOUT_MS = 10000;
16+
17+
// Openverse text lands in markdown and JSON: one line, no control or markdown-structure characters, bounded.
18+
const oneLine = (text) =>
19+
String(text ?? "")
20+
.replace(/[\p{Cc}`[\]<>\\]+/gu, " ")
21+
.trim()
22+
.slice(0, 300);
23+
// Openverse's audio providers (api.openverse.org/v1/audio/stats/); a new provider's link is dropped until listed.
24+
const SOURCE_HOSTS = new Set(["freesound.org", "www.jamendo.com", "commons.wikimedia.org"]);
25+
function httpsUrl(url, hosts) {
26+
try {
27+
const parsed = new URL(url);
28+
return parsed.protocol === "https:" && (!hosts || hosts.has(parsed.hostname))
29+
? oneLine(parsed.href)
30+
: "";
31+
} catch {
32+
return "";
33+
}
34+
}
35+
36+
/** Openverse could not answer (offline, rate limited, server error): stop asking it this run. */
37+
export class OpenverseUnavailableError extends Error {
38+
constructor(message) {
39+
super(message);
40+
this.name = "OpenverseUnavailableError";
41+
}
42+
}
43+
44+
function usable(result) {
45+
return (
46+
OPENVERSE_SFX_LICENSES.has(result?.license) &&
47+
PLAYABLE_FILETYPES.has(result.filetype) &&
48+
typeof result.url === "string" &&
49+
result.url.startsWith("https://") &&
50+
Number.isFinite(result.duration) &&
51+
result.duration > 0 &&
52+
result.duration <= MAX_SFX_MS
53+
);
54+
}
55+
56+
// Lower is better: relevance position, then seconds past a typical cue length, then CC0 over CC BY.
57+
function penalty(result, position) {
58+
const longBy = Math.max(0, result.duration - IDEAL_SFX_MS) / 1000;
59+
return position + longBy + (result.license === "by" ? BY_PENALTY : 0);
60+
}
61+
62+
/** Best usable sound in Openverse's relevance-ordered results, or null. */
63+
export function pickOpenverseSfx(results) {
64+
let best = null;
65+
results.forEach((result, position) => {
66+
if (!usable(result)) return;
67+
const score = penalty(result, position);
68+
if (!best || score < best.score) best = { result, score };
69+
});
70+
if (!best) return null;
71+
const r = best.result;
72+
return {
73+
id: r.id,
74+
url: r.url,
75+
ext: `.${r.filetype}`,
76+
title: oneLine(r.title),
77+
creator: oneLine(r.creator),
78+
license: r.license,
79+
licenseUrl: httpsUrl(r.license_url),
80+
sourceUrl: httpsUrl(r.foreign_landing_url, SOURCE_HOSTS),
81+
credit: oneLine(r.attribution),
82+
durationS: Math.round(r.duration) / 1000,
83+
};
84+
}
85+
86+
/** Best licensed sound effect for `query`, null on no match; throws OpenverseUnavailableError. */
87+
export async function searchOpenverseSfx(query, { fetchImpl = fetch } = {}) {
88+
const params = new URLSearchParams({
89+
q: query,
90+
page_size: "20",
91+
license: [...OPENVERSE_SFX_LICENSES].join(","),
92+
});
93+
let response;
94+
try {
95+
response = await fetchImpl(`${OPENVERSE_AUDIO_URL}?${params}`, {
96+
headers: { Accept: "application/json" },
97+
signal: AbortSignal.timeout(SEARCH_TIMEOUT_MS),
98+
});
99+
} catch (error) {
100+
throw new OpenverseUnavailableError(`Openverse unreachable (${error.message})`);
101+
}
102+
if (response.status === 429)
103+
throw new OpenverseUnavailableError("Openverse rate limit reached (HTTP 429)");
104+
if (!response.ok) throw new OpenverseUnavailableError(`Openverse HTTP ${response.status}`);
105+
let body;
106+
try {
107+
body = await response.json();
108+
} catch {
109+
throw new OpenverseUnavailableError("Openverse returned non-JSON");
110+
}
111+
return pickOpenverseSfx(Array.isArray(body?.results) ? body.results : []);
112+
}
113+
114+
/** Record a CC BY sound's credit for `file` in the project's credits file (one line per file). */
115+
export function writeSfxCredit(creditsPath, file, sound) {
116+
if (sound.license !== "by") return;
117+
// The sound may come from a saved record, not this run's pick: clean it again here.
118+
const sourceUrl = httpsUrl(sound.sourceUrl, SOURCE_HOSTS);
119+
const source = sourceUrl ? ` Source: ${sourceUrl}` : "";
120+
const line = `- \`${file}\`: ${oneLine(sound.credit)}${source}`;
121+
let prior = "";
122+
try {
123+
prior = readFileSync(creditsPath, "utf8");
124+
} catch (error) {
125+
if (error.code !== "ENOENT") throw error;
126+
}
127+
const kept = prior
128+
.split("\n")
129+
.filter((l) => l.startsWith("- ") && !l.startsWith(`- \`${file}\`:`));
130+
const header =
131+
"# Sound effect credits\n\nThese sounds are licensed CC BY: credit them wherever the video is published.\n\n";
132+
mkdirSync(dirname(creditsPath), { recursive: true });
133+
writeFileSync(creditsPath, `${header}${[...kept, line].join("\n")}\n`);
134+
}

0 commit comments

Comments
 (0)