Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
/**
* Pure helpers behind the Identify Speakers modal (#395).
*
* Everything here works on plain data so it can be unit-tested without Vue
* or a browser. The composable (composables/speaker-modal.js) owns the
* reactive state and calls these.
*/
/** Minimum speaking time for a speaker to count as a main participant. */
export const MINOR_SPEAKER_SECONDS = 30;
/**
* Parse a recording's stored transcription for the modal.
*
* Returns { isJson, segments, plainText }. Each segment carries its index in
* the stored array (`index`), which every edit must use.
*/
export function parseModalSegments(transcription) {
if (!transcription) return { isJson: false, segments: [], plainText: '' };
let data = null;
try {
data = JSON.parse(transcription);
} catch (e) {
data = null;
}
if (!Array.isArray(data)) {
return { isJson: false, segments: [], plainText: String(transcription) };
}
const segments = data.map((seg, index) => {
const start = seg.start_time ?? seg.startTime;
const end = seg.end_time ?? seg.endTime;
return {
index,
speakerId: seg.speaker || '',
sentence: seg.sentence || '',
start: typeof start === 'number' && isFinite(start) ? start : null,
end: typeof end === 'number' && isFinite(end) ? end : null,
};
});
return { isJson: true, segments, plainText: '' };
}
/**
* Per-speaker totals.
*
* Returns { hasTimes, totalSeconds, bySpeaker } where bySpeaker maps a
* speaker id to { seconds, share, turns, segments, firstIndex, longestIndex }.
* A turn is a run of consecutive segments by the same speaker.
* hasTimes is false when any segment lacks usable times; seconds and share
* are then 0 and callers fall back to appearance order.
*/
export function computeSpeakerStats(segments) {
const hasTimes = segments.length > 0
&& segments.every(s => s.start !== null && s.end !== null);
const bySpeaker = {};
let totalSeconds = 0;
let previous = null;
for (const seg of segments) {
const id = seg.speakerId;
if (!id) { previous = null; continue; }
let agg = bySpeaker[id];
if (!agg) {
agg = { seconds: 0, share: 0, turns: 0, segments: 0, firstIndex: seg.index,
longestIndex: seg.index, longestSeconds: -1 };
bySpeaker[id] = agg;
}
agg.segments += 1;
if (previous !== id) agg.turns += 1;
previous = id;
if (hasTimes) {
const dur = Math.max(0, seg.end - seg.start);
agg.seconds += dur;
totalSeconds += dur;
if (dur > agg.longestSeconds) {
agg.longestSeconds = dur;
agg.longestIndex = seg.index;
}
}
}
for (const agg of Object.values(bySpeaker)) {
agg.share = hasTimes && totalSeconds > 0 ? Math.round((agg.seconds / totalSeconds) * 100) : 0;
delete agg.longestSeconds;
}
return { hasTimes, totalSeconds, bySpeaker };
}
/**
* Order speaker ids for the list.
*
* mode: 'appearance' (first segment), 'duration' (most speaking time first)
* or 'name' (typed name, then label). Ties keep appearance order, and
* 'duration' without times falls back to appearance.
*/
export function orderSpeakers(ids, stats, mode, nameOf = () => '') {
const first = (id) => stats.bySpeaker[id]?.firstIndex ?? Number.MAX_SAFE_INTEGER;
const byAppearance = (a, b) => first(a) - first(b);
const sorted = [...ids];
if (mode === 'duration' && stats.hasTimes) {
const secs = (id) => stats.bySpeaker[id]?.seconds ?? 0;
sorted.sort((a, b) => (secs(b) - secs(a)) || byAppearance(a, b));
} else if (mode === 'name') {
const key = (id) => (nameOf(id) || '').trim().toLocaleLowerCase() || `${id.toLocaleLowerCase()}`;
sorted.sort((a, b) => key(a).localeCompare(key(b)) || byAppearance(a, b));
} else {
sorted.sort(byAppearance);
}
return sorted;
}
/**
* Split ordered ids into main and minor speakers.
*
* A minor speaker spoke for less than `threshold` seconds in total. Speakers
* that already have a name, and speakers added by hand (no segments yet),
* always stay in the main list. Without times, or when the split would leave
* fewer than two main speakers, nothing is split out.
*/
export function splitMinorSpeakers(orderedIds, stats, threshold = MINOR_SPEAKER_SECONDS, hasName = () => false) {
if (!stats.hasTimes) return { main: [...orderedIds], minor: [] };
const main = [];
const minor = [];
for (const id of orderedIds) {
const agg = stats.bySpeaker[id];
if (agg && agg.seconds < threshold && !hasName(id)) minor.push(id);
else main.push(id);
}
if (main.length < 2 || minor.length === 0) return { main: [...orderedIds], minor: [] };
return { main, minor };
}
const norm = (s) => (s || '').trim().replace(/\s+/g, ' ').toLocaleLowerCase();
/**
* Options for a speaker's name field.
*
* voice: voice-match suggestions for this label, [{ name, similarity }].
* saved: the user's saved speakers from /speakers/search, [{ name, use_count }].
* query: the text typed so far (filters both lists by substring).
* takenNames: names already given to OTHER labels in this modal; they sink
* below the rest (assigning one is a deliberate merge, so they stay offered).
*
* Voice matches come first, duplicates are dropped ignoring case.
*/
export function buildNameOptions({ voice = [], saved = [], query = '', takenNames = [], limit = 8 }) {
const q = norm(query);
const taken = new Set(takenNames.map(norm));
const seen = new Set();
const out = [];
const push = (opt) => {
const key = norm(opt.name);
if (!key || seen.has(key)) return;
if (q && !key.includes(q)) return;
seen.add(key);
out.push({ ...opt, taken: taken.has(key) });
};
for (const v of voice) push({ name: v.name, source: 'voice', similarity: v.similarity });
for (const s of saved) push({ name: s.name, source: 'saved', useCount: s.use_count ?? s.useCount ?? 0 });
const free = out.filter(o => !o.taken);
const used = out.filter(o => o.taken);
return [...free, ...used].slice(0, limit);
}
/**
* The saved spelling of `name` when it differs only in case or spacing,
* otherwise null. The server applies the saved spelling on save; the modal
* shows it first so the user is not surprised.
*/
export function findSavedSpelling(name, savedNames) {
const key = norm(name);
if (!key) return null;
for (const saved of savedNames) {
if (norm(saved) === key && saved !== name.trim()) return saved;
}
return null;
}
/**
* Index into `segments` of the segment playing at `time`, or -1.
* Segments are in time order; uses a binary search on start times.
*/
export function playingSegmentPosition(segments, time) {
if (!segments.length || time === null || time === undefined || !isFinite(time)) return -1;
let lo = 0;
let hi = segments.length - 1;
let found = -1;
while (lo <= hi) {
const mid = (lo + hi) >> 1;
const start = segments[mid].start;
if (start === null) return -1;
if (start <= time) { found = mid; lo = mid + 1; } else { hi = mid - 1; }
}
if (found === -1) return -1;
const seg = segments[found];
return seg.end !== null && time <= seg.end + 0.25 ? found : -1;
}
/**
* Turn groups for one speaker: positions (into `segments`) where a run of
* that speaker starts. Used for Previous / Next when the list is unfiltered.
*/
export function turnStarts(segments, speakerId) {
const starts = [];
let previous = null;
segments.forEach((seg, pos) => {
if (seg.speakerId === speakerId && previous !== speakerId) starts.push(pos);
previous = seg.speakerId;
});
return starts;
}
/** m:ss or h:mm:ss for a number of seconds. */
export function formatClock(seconds) {
if (seconds === null || seconds === undefined || !isFinite(seconds) || seconds < 0) return '0:00';
const total = Math.floor(seconds);
const h = Math.floor(total / 3600);
const m = Math.floor((total % 3600) / 60);
const s = total % 60;
const ss = String(s).padStart(2, '0');
return h > 0 ? `${h}:${String(m).padStart(2, '0')}:${ss}` : `${m}:${ss}`;
}
/**
* Reassign every segment of `sourceIds` to `targetId` in a stored
* transcription array (not mutated). Returns the new array and how many
* segments moved.
*/
export function mergeSpeakerSegments(transcriptionData, sourceIds, targetId) {
const sources = new Set(sourceIds.filter(id => id && id !== targetId));
let moved = 0;
const data = transcriptionData.map(seg => {
if (sources.has(seg.speaker)) {
moved += 1;
return { ...seg, speaker: targetId };
}
return seg;
});
return { data, moved };
}