vocnu 0.8.0 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -24,9 +24,9 @@ starts, follows the job with its progress, and saves the results next to the fil
24
24
 
25
25
  | Option | |
26
26
  | --- | --- |
27
- | `--output video\|audio\|subtitles` | the video with the voice-over (default for video files), the voice-over audio, or subtitles only |
27
+ | `--output subtitles\|video\|audio` | subtitles only, where your time lasts longest, the video with the voice-over (default for video files), or the voice-over audio |
28
28
  | `--from <lang>` | spoken language (detected by default) |
29
- | `--grade premium\|standard\|economy` | Premium (default); Standard: simpler voices and translation, and your time lasts twice as long (its subtitles alone are Premium's); or Economy, where your time lasts longest: a voice-over or subtitles alone by a plain synthetic voice reading a quick translation. Standard and Economy where Vocnu offers them |
29
+ | `--grade standard\|premium` | Standard, where your time lasts longest (several times as long as in Premium): a quick translation, read by a plain synthetic voice in a voice-over; or Premium, the best voices and translation. Default: the grade you chose in Vocnu, else Standard, and Premium where Standard does not make it (a voice-over in a language it has no voices of). Scripts that name Standard by its id still get Standard |
30
30
  | `--voice male\|female\|<voice id>` | a voice type, read by the language's default voice of it (default: male), or a voice from `vocnu voices <lang>` |
31
31
  | `--format mp4\|mkv\|mov\|webm\|avi` | video file format, or several separated by commas (`--format mp4,mkv`: one file each, for the price of the dearest); default: the upload's own, else MP4 |
32
32
  | `--audio-format m4a\|mp3\|wav\|flac\|ogg` | voice-over audio format |
@@ -38,20 +38,24 @@ starts, follows the job with its progress, and saves the results next to the fil
38
38
  | `--yes` | start without confirming the price |
39
39
  | `--no-wait` | start the job and return its id |
40
40
 
41
- `vocnu voices <lang>` lists the voices of a language with a link to a short sample of each, Premium's, or
42
- another grade's with `--grade standard` or `--grade economy`: a job names a voice of its own grade. Other commands:
41
+ `vocnu voices <lang>` lists the voices of a language with a link to a short sample of each, your grade's, or
42
+ another's with `--grade`: a job names a voice of its own grade. Other commands:
43
43
  `vocnu languages`, `vocnu jobs`, `vocnu status <job>`, `vocnu download <job>`, `vocnu cancel <job>`, `vocnu logout`.
44
44
 
45
45
  ## Your time
46
46
 
47
47
  ```sh
48
- npx vocnu time # time left in each grade, your plan and what expires
48
+ npx vocnu time # time left of subtitles and voice-over, your plan and what expires
49
49
  npx vocnu time --json # the same for scripts
50
50
  ```
51
51
 
52
- Your balance is time: what it covers in Premium, twice as long in Standard and four times as long in Economy. With
53
- `--json` the report also carries `balance` and each part's `credits`, the unit Vocnu counts in, beside
54
- `balance_minutes` and `balance_time`. `vocnu credits` still works as before.
52
+ Your balance is time, told first in your grade and in what you make: subtitles alone, unless you chose a voice-over in
53
+ Vocnu, with the other beside it (`Time left: 8 h of Standard subtitles, or 6 h of voice-over`), then in the other
54
+ grade. Subtitles alone last longest, and Standard several times as long as Premium. A price is told the same way, in
55
+ the time of what the job makes: `This uses 12 min of Standard subtitles`. With `--json` the report also carries
56
+ `balance` and each part's `credits`, the unit Vocnu counts in, beside the minutes and the time of voice-over
57
+ (`balance_minutes`, `balance_time`) and of subtitles alone (`subtitles_minutes`, `subtitles_time`) in each grade.
58
+ `vocnu credits` still works as before.
55
59
 
56
60
  ## Share the results
57
61
 
@@ -86,13 +90,15 @@ Claude Desktop (`claude_desktop_config.json`) and other MCP clients:
86
90
  ```
87
91
 
88
92
  Then ask, for example, “Dub ~/Videos/film.mkv into Lithuanian with Vocnu”. The assistant uploads the file
89
- (`vocnu_upload_media`), tells you the price of each grade, starts the job only after you agree (`vocnu_start_job`,
90
- Premium unless you ask for Standard or Economy), checks on it
93
+ (`vocnu_upload_media`), tells you the price in your grade, Standard unless you chose Premium in Vocnu, and in the
94
+ other grade, in the time of what it makes (subtitles alone or a voice-over), starts the job only after you agree
95
+ (`vocnu_start_job`, `grade` "standard" or "premium"), checks on it
91
96
  (`vocnu_job_status`) and saves the files (`vocnu_download_results`) or gives you a link to send
92
97
  (`vocnu_share_job`, turned off with `vocnu_revoke_share`). Also: `vocnu_languages`, `vocnu_voices` (the voices of a
93
- language and grade with their samples, for `vocnu_start_job`'s `voice_id`), `vocnu_credits` (the time left in each
94
- grade, the plan and what expires), `vocnu_list_jobs`, `vocnu_cancel_job`. Every price and balance comes as time
95
- (`price_time`, `balance_time`, `balance_after_time`) beside the same in credits, so the assistant tells you time.
98
+ language and grade with their samples, for `vocnu_start_job`'s `voice_id`), `vocnu_credits` (the time left of what
99
+ you make, `time_left`, and in each grade, the plan and what expires), `vocnu_list_jobs`, `vocnu_cancel_job`. Every
100
+ price and balance comes as time (`price_time`, `balance_time`, `balance_after_time`) beside the same in credits, so
101
+ the assistant tells you time.
96
102
 
97
103
  ## Development
98
104
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vocnu",
3
- "version": "0.8.0",
3
+ "version": "0.9.1",
4
4
  "description": "Vocnu from your terminal and your AI assistant: AI voice-over and subtitles for your videos (CLI and MCP server).",
5
5
  "type": "module",
6
6
  "bin": {
package/src/api.js CHANGED
@@ -63,6 +63,12 @@ export class VocnuApi {
63
63
  return this.request('GET', '/credits')
64
64
  }
65
65
 
66
+ // The person's preferences the app and the extension share (backend ADR 0054), the grade to suggest among them: the
67
+ // one they chose, else Vocnu's default (backend ADR 0126).
68
+ async preferences() {
69
+ return (await this.request('GET', '/preferences')).preferences
70
+ }
71
+
66
72
  // Vocnu's voice catalog for a language (backend ADR 0026): voices a job may name, each with a short sample. Premium's
67
73
  // unless `grade` names another (backend ADR 0080).
68
74
  async voices(language, grade) {
package/src/cli.js CHANGED
@@ -8,10 +8,11 @@ import { parseArgs } from 'node:util'
8
8
  import { VocnuApi, VocnuError } from './api.js'
9
9
  import { credentialsPath, DEFAULT_URL, forgetCredentials, loadConfig, saveCredentials } from './config.js'
10
10
  import { formatTimeLeft, secondsLeft } from './estimate.js'
11
- import { balanceLines, balanceReport, catalogOf, costGrade, gradeTime, secondsPerCredit } from './hours.js'
11
+ import { currentGrade, gradeFrom, gradeMakes, jobGrade, modeFrom, preferencesOf, preferredGrade } from './grades.js'
12
+ import { balanceLines, balanceReport, balanceTime, catalogOf, offeredGrades, productTime, timesOf } from './hours.js'
12
13
  import {
13
- AUDIO_FORMATS, contentType, defaultVideoFormat, GRADE_NAMES, GRADES, gradeQuote, isVideo, OUTPUTS, productsFor, quotedCredits,
14
- SUBTITLE_GRADES, VIDEO_FORMATS, videoFormatsFrom,
14
+ AUDIO_FORMATS, contentType, defaultVideoFormat, GRADE_ARGUMENT, GRADE_ARGUMENTS, GRADE_NAMES, GRADES, gradeQuote, isVideo,
15
+ OUTPUTS, productsFor, quotedCredits, VIDEO_FORMATS, videoFormatsFrom,
15
16
  } from './media.js'
16
17
  import { VERSION } from './version.js'
17
18
 
@@ -22,16 +23,19 @@ const HELP = `Vocnu ${VERSION}: AI voice-over and subtitles for your videos (htt
22
23
  Usage:
23
24
  vocnu login [--token <token>] Save an API token (app.vocnu.com → Settings → API & MCP)
24
25
  vocnu logout Forget the saved token
25
- vocnu time [--json] Your time left in each grade, your plan and what expires
26
+ vocnu time [--json] Your time left of subtitles and voice-over in each grade, your plan
27
+ and what expires
26
28
  vocnu languages Languages you can translate into
27
29
  vocnu voices <lang> Voices of a language, each with a short sample to listen to
28
- --grade premium|standard|economy Another grade's voices instead of Premium's
30
+ --grade standard|premium Whose voices (default: your grade's)
29
31
  vocnu translate <file> --to <lang> Upload, see the price, translate and download the results
30
- --output video|audio|subtitles What you get (default: video for a video file, else audio)
31
- --grade premium|standard|economy Premium (default); Standard: simpler voices and translation, and your
32
- time lasts twice as long; or Economy, where it lasts longest: a plain
33
- synthetic voice reading a quick translation, for a voice-over or subtitles
34
- alone (Standard and Economy where Vocnu offers them)
32
+ --output subtitles|video|audio What you get: subtitles only, where your time lasts longest, or the
33
+ voice-over in the video or as audio (default: video for a video
34
+ file, else audio)
35
+ --grade standard|premium Standard, where your time lasts longest: a quick translation,
36
+ read by a plain synthetic voice in a voice-over; or Premium.
37
+ Default: the grade you chose in Vocnu, else Standard (Premium
38
+ where Standard does not make it)
35
39
  --from <lang> Spoken language (default: detected)
36
40
  --voice male|female|<voice id> A voice type, or a voice from \`vocnu voices\` (default: male)
37
41
  --format mp4|mkv|mov|webm|avi Video file format, or several: mp4,mkv (default: the upload's, else mp4)
@@ -88,7 +92,7 @@ export async function main(argv, { env = process.env, out = process.stdout, err
88
92
  case 'languages':
89
93
  return await languages(api, print)
90
94
  case 'voices':
91
- return await voices(rest, { api, print })
95
+ return await voices(rest, { api, err, print })
92
96
  case 'translate':
93
97
  return await translate(rest, { api, err, out, print })
94
98
  case 'jobs':
@@ -121,11 +125,15 @@ function required(value, what) {
121
125
  return value
122
126
  }
123
127
 
124
- function checkGrade(grade) {
125
- if (grade !== undefined && !GRADES.includes(grade)) throw new UsageError(`--grade is ${listed(GRADES)}.`)
128
+ // The grade asked with --grade, undefined for none. `standard`, the name people know Standard by (backend ADR 0127),
129
+ // and its id `economy`, which scripts written before may use, are both `economy`.
130
+ function askedGrade(grade) {
131
+ if (grade === undefined) return undefined
132
+ if (!GRADE_ARGUMENTS.includes(grade)) throw new UsageError(`--grade is ${listed(GRADES.map((name) => GRADE_ARGUMENT[name]))}.`)
133
+ return currentGrade(grade)
126
134
  }
127
135
 
128
- // premium, standard or economy
136
+ // standard or premium
129
137
  function listed(names) {
130
138
  return names.length > 1 ? `${names.slice(0, -1).join(', ')} or ${names.at(-1)}` : names.join('')
131
139
  }
@@ -145,19 +153,27 @@ async function login(args, { api, config, env, print }) {
145
153
  const url = (values.url ?? config.url ?? DEFAULT_URL).replace(/\/+$/, '')
146
154
  const checked = new VocnuApi({ fetch: api.fetch, token, url })
147
155
  const { balance } = await checked.credits()
148
- const left = gradeTime(balance, 'premium', secondsPerCredit(await catalogOf(checked)), 'down')
156
+ // Told in the person's own grade, Standard (`economy`) until they choose (backend ADR 0126), and in what they use,
157
+ // subtitles alone until they choose a voice-over (ADR 0129).
158
+ const [catalog, preferences] = await Promise.all([catalogOf(checked), preferencesOf(checked)])
159
+ const left = balanceTime(balance, gradeFrom(preferences, catalog), modeFrom(preferences), timesOf(catalog))
149
160
  const path = await saveCredentials({ token, url }, env)
150
161
  print(`Signed in (${left} left). Token saved in ${path}.`)
151
162
  return 0
152
163
  }
153
164
 
154
- // The time the balance voices in each grade, the plan and what expires; `--json` adds the credits Vocnu counts in.
165
+ // The time the balance lasts in the person's grade of what they use, then of the rest, the plan and what expires
166
+ // (backend ADR 0129); `--json` adds the credits Vocnu counts in.
155
167
  async function timeLeft(args, { api, print }) {
156
168
  const { values } = parse(args, { json: { type: 'boolean' } })
157
169
  const [answer, catalog] = await Promise.all([api.credits(), catalogOf(api)])
158
170
  const report = balanceReport(answer, catalog)
159
- if (values.json) print(JSON.stringify(report, null, 2))
160
- else for (const line of balanceLines(report)) print(line)
171
+ if (values.json) {
172
+ print(JSON.stringify(report, null, 2))
173
+ return 0
174
+ }
175
+ const preferences = await preferencesOf(api)
176
+ for (const line of balanceLines(report, gradeFrom(preferences, catalog), modeFrom(preferences))) print(line)
161
177
  return 0
162
178
  }
163
179
 
@@ -169,11 +185,18 @@ async function languages(api, print) {
169
185
  return 0
170
186
  }
171
187
 
172
- async function voices(args, { api, print }) {
188
+ // A grade's voices of a language: the grade asked, else the person's own where it reads the language, else Premium's.
189
+ async function voices(args, { api, err, print }) {
173
190
  const { positionals, values } = parse(args, { grade: { type: 'string' } })
174
191
  const language = required(positionals[0], 'language code')
175
- checkGrade(values.grade)
176
- for (const voice of await api.voices(language, values.grade)) {
192
+ const asked = askedGrade(values.grade)
193
+ const catalog = asked === undefined ? await catalogOf(api) : null
194
+ const grade = asked ?? (await jobGrade(api, catalog, 'audio', language))
195
+ if (asked === undefined && offeredGrades(catalog).length > 1) {
196
+ const other = offeredGrades(catalog).find((name) => name !== grade)
197
+ err.write(`${GRADE_NAMES[grade]} voices; add --grade ${GRADE_ARGUMENT[other]} for ${GRADE_NAMES[other]}'s.\n`)
198
+ }
199
+ for (const voice of await api.voices(language, grade)) {
177
200
  const about = [voice.gender, ...(voice.traits ?? [])].join(', ')
178
201
  print(`${voice.id.padEnd(24)} ${voice.name} (${about})${voice.default ? ', default' : ''}`)
179
202
  print(`${''.padEnd(24)} ${voice.sample_url}`)
@@ -211,14 +234,7 @@ async function translate(args, { api, err, out, print }) {
211
234
  const originalLevel = values['original-level']
212
235
  // Or none of the original at all, between the lines too (backend ADR 0067).
213
236
  const originalOff = values['original-off'] === true
214
- // Premium unless asked (backend ADR 0080); a job that names none is Premium's on every server.
215
- const grade = values.grade ?? 'premium'
216
- checkGrade(values.grade)
217
- // Subtitles alone come in Premium or in Economy's own translation; Standard's would be Premium's.
218
- if (output === 'subtitles' && !SUBTITLE_GRADES.includes(grade)) {
219
- const names = listed(SUBTITLE_GRADES.map((name) => GRADE_NAMES[name]))
220
- throw new UsageError(`--grade ${grade} is for a voice-over: subtitles alone come in ${names}.`)
221
- }
237
+ const asked = askedGrade(values.grade)
222
238
  if (!OUTPUTS.includes(output)) throw new UsageError(`--output is one of ${OUTPUTS.join(', ')}.`)
223
239
  if (!videoFormats) throw new UsageError(`--format is one or more of ${VIDEO_FORMATS.join(', ')}, separated by commas.`)
224
240
  if (!AUDIO_FORMATS.includes(audioFormat)) throw new UsageError(`--audio-format is one of ${AUDIO_FORMATS.join(', ')}.`)
@@ -231,9 +247,34 @@ async function translate(args, { api, err, out, print }) {
231
247
  if (originalOff && originalLevel !== undefined) throw new UsageError('--original-off leaves no original to set a level for: use one of them.')
232
248
  if (output === 'video' && !isVideo(path)) throw new UsageError('This is an audio file: use --output audio or subtitles.')
233
249
  if (!contentType(path)) throw new UsageError('Vocnu takes video and audio files (MP4, MOV, MKV, WebM, MP3, M4A, WAV...).')
234
- if (voice !== voiceType && !(await api.voices(target, values.grade)).some((candidate) => candidate.id === voice)) {
235
- const listing = `vocnu voices ${target}${values.grade ? ` --grade ${grade}` : ''}`
236
- throw new UsageError(`${target} has no ${values.grade ? `${GRADE_NAMES[grade]} ` : ''}voice ${voice}: see \`${listing}\`.`)
250
+ const catalog = await catalogOf(api)
251
+ // Without --grade, the person's own grade (backend ADR 0126), Standard (`economy`) until they choose, where it makes this output
252
+ // into this language, else Premium; a voice id is read in the grade whose voice it is.
253
+ let grade = asked
254
+ if (grade === undefined) {
255
+ const preferred = await preferredGrade(api, catalog)
256
+ grade = gradeMakes(catalog, preferred, output, target) ? preferred : 'premium'
257
+ if (grade !== preferred) {
258
+ const why = output === 'subtitles' ? 'makes no subtitles alone' : `reads no voice-over in ${target}`
259
+ print(`${GRADE_NAMES[preferred]} ${why} yet, so this is ${GRADE_NAMES[grade]}.`)
260
+ }
261
+ }
262
+ if (voice !== voiceType) {
263
+ const candidates = asked === undefined
264
+ ? [grade, ...offeredGrades(catalog).filter((name) => name !== grade && gradeMakes(catalog, name, output, target))]
265
+ : [asked]
266
+ let found = null
267
+ for (const candidate of candidates) {
268
+ if ((await api.voices(target, candidate)).some((known) => known.id === voice)) {
269
+ found = candidate
270
+ break
271
+ }
272
+ }
273
+ if (found === null) {
274
+ const listing = `vocnu voices ${target}${asked ? ` --grade ${GRADE_ARGUMENT[asked]}` : ''}`
275
+ throw new UsageError(`${target} has no ${asked ? `${GRADE_NAMES[asked]} ` : ''}voice ${voice}: see \`${listing}\`.`)
276
+ }
277
+ grade = found
237
278
  }
238
279
  const { size } = await stat(path)
239
280
 
@@ -244,22 +285,31 @@ async function translate(args, { api, err, out, print }) {
244
285
  source = await api.waitForSource(source.id)
245
286
  progress.done(`Ready: ${source.title ?? basename(path)}, ${formatDuration(source.duration_seconds)}`)
246
287
 
288
+ // A grade this upload is not priced in: asked for, or a voice of it named, nothing starts; else Premium makes it.
289
+ if (!gradeQuote(source.quote, grade)) {
290
+ if (asked !== undefined || voice !== voiceType) {
291
+ throw new VocnuError(`${GRADE_NAMES[grade]} is not available yet: use --grade premium. Nothing was charged.`)
292
+ }
293
+ grade = 'premium'
294
+ }
247
295
  const prices = gradeQuote(source.quote, grade)
248
- if (!prices) throw new VocnuError(`${GRADE_NAMES[grade]} is not available yet: use --grade premium. Nothing was charged.`)
249
296
  const choice = [output, videoFormats, values['burn-subtitles'], values.sdh]
250
297
  const credits = quotedCredits(prices, ...choice)
251
- const [{ balance }, catalog] = await Promise.all([api.credits(), catalogOf(api)])
252
- // Told as time of the grade it is made in, subtitles alone in Standard's or Economy's (backend ADR 0122).
253
- const seconds = secondsPerCredit(catalog)
254
- const told = costGrade(grade, output !== 'subtitles')
298
+ const { balance } = await api.credits()
299
+ // Told as time of what the job makes in its grade, subtitles alone in their own time, never a voice-over's (backend
300
+ // ADR 0122, 0126, 0129); where nobody gave their rate, the file's length alone.
301
+ const times = timesOf(catalog, source.quote)
302
+ const voiced = output !== 'subtitles'
255
303
  const fileMinutes = source.quote.minutes
256
- print(`This uses ${gradeTime(credits, told, seconds, 'up')} (the file is ${fileMinutes} min). `
257
- + `You have ${gradeTime(balance, told, seconds, 'down')} left.`)
304
+ const price = productTime(credits, grade, voiced, times, 'up')
305
+ print(price === null
306
+ ? `This makes ${GRADE_NAMES[grade]} subtitles of the file (${fileMinutes} min).`
307
+ : `This uses ${price} (the file is ${fileMinutes} min). You have ${productTime(balance, grade, voiced, times, 'down')} left.`)
258
308
  // Short of time in the grade asked, the cheaper grades the balance covers say so.
259
309
  if (credits > balance) {
260
- const cheaper = await cheaperWithin(api, source.quote, { balance, choice, grade, output, target })
310
+ const cheaper = await cheaperWithin(api, source.quote, { balance, choice, credits, grade, output, target })
261
311
  if (cheaper.length > 0) {
262
- const offers = cheaper.map((name) => `${GRADE_NAMES[name]} (add --grade ${name})`)
312
+ const offers = cheaper.map((name) => `${GRADE_NAMES[name]} (add --grade ${GRADE_ARGUMENT[name]})`)
263
313
  print(`Not enough time left for ${GRADE_NAMES[grade]}: it fits in ${offers.join(' or ')}.`)
264
314
  }
265
315
  }
@@ -283,9 +333,11 @@ async function translate(args, { api, err, out, print }) {
283
333
  ...(voice === voiceType ? {} : { voice_id: voice }),
284
334
  ...(originalLevel === undefined ? {} : { original_level: Number(originalLevel) }),
285
335
  ...(originalOff ? { original_off: true } : {}),
286
- ...(values.grade === undefined ? {} : { grade }),
336
+ // A job that names no grade is Premium's on every server, so Premium's names none.
337
+ ...(grade === 'premium' ? {} : { grade }),
287
338
  })
288
- print(`Started job ${created.job.id} (${gradeTime(created.credit_balance, told, seconds, 'down')} left).`)
339
+ const after = productTime(created.credit_balance, grade, voiced, times, 'down')
340
+ print(after === null ? `Started job ${created.job.id}.` : `Started job ${created.job.id} (${after} left).`)
289
341
  if (values['no-wait']) return 0
290
342
 
291
343
  const job = await follow(api, created.job.id, progress)
@@ -298,20 +350,19 @@ async function translate(args, { api, err, out, print }) {
298
350
  return 0
299
351
  }
300
352
 
301
- // The grades cheaper than the one asked, dearest first, whose price the balance covers: Standard and Economy for a
302
- // voice-over where they have voices of the language, Economy for subtitles alone.
303
- async function cheaperWithin(api, quote, { balance, choice, grade, output, target }) {
304
- const grades = output === 'subtitles' ? SUBTITLE_GRADES : GRADES
353
+ // The grades cheaper than the one chosen, dearest first, whose price the balance covers: Standard (`economy`), for a voice-over
354
+ // where it has voices of the language.
355
+ async function cheaperWithin(api, quote, { balance, choice, credits, grade, output, target }) {
305
356
  const within = []
306
- for (const cheaper of grades.slice(grades.indexOf(grade) + 1)) {
307
- const prices = gradeQuote(quote, cheaper)
357
+ for (const other of GRADES.filter((name) => name !== grade)) {
358
+ const prices = gradeQuote(quote, other)
308
359
  if (!prices) continue
309
- const credits = quotedCredits(prices, ...choice)
310
- if (credits > balance) continue
311
- if (output !== 'subtitles' && (await api.voices(target, cheaper)).length === 0) continue
312
- within.push(cheaper)
360
+ const cost = quotedCredits(prices, ...choice)
361
+ if (cost >= credits || cost > balance) continue
362
+ if (output !== 'subtitles' && (await api.voices(target, other)).length === 0) continue
363
+ within.push([cost, other])
313
364
  }
314
- return within
365
+ return within.sort((a, b) => b[0] - a[0]).map(([, other]) => other)
315
366
  }
316
367
 
317
368
  async function follow(api, id, progress) {
package/src/grades.js ADDED
@@ -0,0 +1,51 @@
1
+ // Which grade a job is made in when none is named (backend ADR 0126): the person's own, which Vocnu keeps for the app,
2
+ // the extension and this CLI alike (`economy`, called Standard, until they choose, where Vocnu offers it), else Vocnu's
3
+ // default, else `economy` where offered, else Premium. The old `standard`, retired, reads as `economy`: a silent move
4
+ // to Premium would double what a script pays.
5
+ import { offeredGrades } from './hours.js'
6
+ import { SUCCESSORS } from './media.js'
7
+
8
+ export function currentGrade(grade) {
9
+ return SUCCESSORS[grade] ?? grade
10
+ }
11
+
12
+ // The person's preferences the app and the extension share, or none where they cannot be read (an older Vocnu, a
13
+ // token without them).
14
+ export async function preferencesOf(api) {
15
+ return Promise.resolve().then(() => api.preferences()).catch(() => null)
16
+ }
17
+
18
+ // The person's grade among those offered, from preferences already read.
19
+ export function gradeFrom(preferences, catalog) {
20
+ const offered = offeredGrades(catalog)
21
+ for (const candidate of [preferences?.grade, catalog?.default_grade]) {
22
+ const grade = currentGrade(candidate)
23
+ if (offered.includes(grade)) return grade
24
+ }
25
+ return offered.includes('economy') ? 'economy' : 'premium'
26
+ }
27
+
28
+ // What the person uses (backend ADR 0129): `voice` once they chose a voice-over in Vocnu, else subtitles alone.
29
+ export function modeFrom(preferences) {
30
+ return preferences?.mode === 'voice' ? 'voice' : 'subtitles'
31
+ }
32
+
33
+ export async function preferredGrade(api, catalog) {
34
+ return gradeFrom(await preferencesOf(api), catalog)
35
+ }
36
+
37
+ // Whether a grade makes this output into this language, by the catalog: a voice-over where the grade reads the
38
+ // language, subtitles alone where it translates them. Premium makes everything; a catalog that cannot be read or does
39
+ // not say leaves the other grades out.
40
+ export function gradeMakes(catalog, grade, output, language) {
41
+ if (grade === 'premium') return true
42
+ if (output === 'subtitles') return (catalog?.subtitles_grades ?? []).includes(grade)
43
+ const known = (catalog?.languages ?? []).find((candidate) => candidate.code === language)
44
+ return (known?.voiceover_grades ?? []).includes(grade)
45
+ }
46
+
47
+ // The grade for this output and language when none is named: the person's own where it makes them, else Premium.
48
+ export async function jobGrade(api, catalog, output, language) {
49
+ const preferred = await preferredGrade(api, catalog)
50
+ return gradeMakes(catalog, preferred, output, language) ? preferred : 'premium'
51
+ }
package/src/hours.js CHANGED
@@ -1,11 +1,13 @@
1
- // Time instead of credits (backend ADR 0122): people see how long their balance voices, never credits. A credit voices
2
- // 30 seconds of Premium, a minute of Standard and two minutes of Economy, as Vocnu's catalog says for each grade
3
- // (`seconds_per_credit`, else a minute over the grade's rate of a voice-over); until it says, those. Times are written
4
- // as the app writes them: "25 min", "1 h", "2 h 5 min". Credits stay what Vocnu counts in, so `--json` and the MCP
5
- // tools keep them beside the time.
6
- import { GRADE_NAMES, GRADES } from './media.js'
1
+ // Time instead of credits (backend ADR 0122, 0126, 0129): people see how long their balance lasts, never credits, in the
2
+ // time of what it makes. A credit voices 30 seconds of Premium and two minutes of Standard (the grade `economy`), as
3
+ // Vocnu's catalog says for each grade (`seconds_per_credit`, else a minute over the grade's rate of a voice-over); until
4
+ // it says, those. Subtitles alone last as long as a minute over their own rate in the grade, as the catalog or an
5
+ // upload's quote says, and where neither says they get no time, never a voice-over's. Times are written as the app
6
+ // writes them: "25 min", "1 h", "2 h 5 min". Credits stay what Vocnu counts in, so `--json` and the MCP tools keep them
7
+ // beside the time.
8
+ import { GRADE_NAMES, GRADES, gradeQuote } from './media.js'
7
9
 
8
- export const SECONDS_PER_CREDIT = { premium: 30, standard: 60, economy: 120 }
10
+ export const SECONDS_PER_CREDIT = { premium: 30, economy: 120 }
9
11
 
10
12
  function positive(value) {
11
13
  return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null
@@ -30,13 +32,30 @@ export function secondsPerCredit(catalog) {
30
32
  }))
31
33
  }
32
34
 
33
- // The grades on offer, Premium first: Premium alone where the catalog names no other.
35
+ // How long a credit lasts in subtitles alone in each grade (backend ADR 0129): a minute over the grade's rate of them,
36
+ // as the catalog says, else as an upload's quote does; null where neither says.
37
+ export function subtitlesSecondsPerCredit(catalog, quote) {
38
+ return Object.fromEntries(GRADES.map((grade) => {
39
+ const rates = catalog?.grades?.[grade]?.rates ?? (grade === 'premium' ? catalog?.rates : undefined)
40
+ const quoted = quote ? gradeQuote(quote, grade)?.credits_per_minute : undefined
41
+ const rate = positive(rates?.subtitles) ?? positive(quoted?.subtitles)
42
+ return [grade, rate === null ? null : 60 / rate]
43
+ }))
44
+ }
45
+
46
+ // How long a credit lasts of each product in each grade: `voice` for a voice-over, `subtitles` for subtitles alone.
47
+ export function timesOf(catalog, quote) {
48
+ return { subtitles: subtitlesSecondsPerCredit(catalog, quote), voice: secondsPerCredit(catalog) }
49
+ }
50
+
51
+ // The grades on offer, Standard (`economy`), the cheaper, first: Premium alone where the catalog names no other. The
52
+ // old `standard` an older Vocnu still lists is never one.
34
53
  export function offeredGrades(catalog) {
35
54
  return GRADES.filter((grade) => grade === 'premium' || catalog?.grades?.[grade])
36
55
  }
37
56
 
38
57
  // Whole minutes the credits voice: down for what a balance surely covers, up for what something uses, so neither says
39
- // more than it gives. Exact to the thousandth first, so half a credit of Economy is a minute, not a hair under one.
58
+ // more than it gives. Exact to the thousandth first, so half a credit of Standard is a minute, not a hair under one.
40
59
  export function minutesOf(credits, seconds, round) {
41
60
  const exact = Math.round(((Math.max(0, credits) * seconds) / 60) * 1000) / 1000
42
61
  return round === 'up' ? Math.ceil(exact) : Math.floor(exact)
@@ -51,21 +70,19 @@ export function duration(minutes) {
51
70
  return rest === 0 ? `${hours} h` : `${hours} h ${rest} min`
52
71
  }
53
72
 
54
- // Credits as time of a grade, the grade named: "4 h 20 min of Premium".
55
- export function gradeTime(credits, grade, seconds, round) {
56
- return `${duration(minutesOf(credits, seconds[grade], round))} of ${GRADE_NAMES[grade]}`
57
- }
58
-
59
- // Which grade's time a cost is told in: a voice-over's own grade; subtitles alone, which cost what Standard's
60
- // voice-over does a minute (Economy's what Economy's does), in Standard's or Economy's.
61
- export function costGrade(grade, voiced) {
62
- if (voiced) return grade
63
- return grade === 'economy' ? 'economy' : 'standard'
73
+ // Credits as time of what they make in a grade, both named (backend ADR 0129): "2 min of Standard subtitles", "1 h of
74
+ // Premium voice-over". Null for subtitles alone whose rate nobody gave: they are never told in a voice-over's time.
75
+ export function productTime(credits, grade, voiced, times, round) {
76
+ const seconds = (voiced ? times.voice : times.subtitles)[grade]
77
+ if (!seconds) return null
78
+ return `${duration(minutesOf(credits, seconds, round))} of ${GRADE_NAMES[grade]} ${voiced ? 'voice-over' : 'subtitles'}`
64
79
  }
65
80
 
81
+ // Whole minutes and the same written, in each grade that has a time for them (`seconds` null leaves a grade out).
66
82
  function byGrade(credits, grades, seconds, round) {
67
- const minutes = Object.fromEntries(grades.map((grade) => [grade, minutesOf(credits, seconds[grade], round)]))
68
- const time = Object.fromEntries(grades.map((grade) => [grade, duration(minutes[grade])]))
83
+ const timed = grades.filter((grade) => seconds[grade])
84
+ const minutes = Object.fromEntries(timed.map((grade) => [grade, minutesOf(credits, seconds[grade], round)]))
85
+ const time = Object.fromEntries(timed.map((grade) => [grade, duration(minutes[grade])]))
69
86
  return { minutes, time }
70
87
  }
71
88
 
@@ -74,18 +91,20 @@ function day(value) {
74
91
  }
75
92
 
76
93
  // The balance as Vocnu's GET credits and catalog say it (`vocnu time --json`, vocnu_credits): the credits as Vocnu
77
- // counts them, the minutes they voice in each grade on offer and the same written, the monthly plan where there is one
78
- // (null before plans or without one) and the credits that expire, soonest first, each with its time. The Library is
79
- // unlimited only where Vocnu says so of the plan.
94
+ // counts them, the minutes of voice-over they cover in each grade on offer (`balance_minutes`, as before) and of
95
+ // subtitles alone in each grade with a rate of them (`subtitles_minutes`, backend ADR 0129), each also written, the
96
+ // monthly plan where there is one (null before plans or without one) and the credits that expire, soonest first, each
97
+ // with its time. The Library is unlimited only where Vocnu says so of the plan.
80
98
  export function balanceReport(credits, catalog) {
81
- const seconds = secondsPerCredit(catalog)
99
+ const times = timesOf(catalog)
82
100
  const grades = offeredGrades(catalog)
101
+ const both = (amount) => ({ voice: byGrade(amount, grades, times.voice, 'down'), subtitles: byGrade(amount, grades, times.subtitles, 'down') })
83
102
  const balance = typeof credits?.balance === 'number' ? credits.balance : 0
84
- const left = byGrade(balance, grades, seconds, 'down')
103
+ const left = both(balance)
85
104
  const raw = credits?.plan
86
105
  const name = typeof raw?.name === 'string' ? raw.name.trim() : ''
87
106
  const monthly = positive(raw?.monthly_credits)
88
- const month = monthly === null ? null : byGrade(monthly, grades, seconds, 'down')
107
+ const month = monthly === null ? null : both(monthly)
89
108
  const plan = name === '' ? null : {
90
109
  id: typeof raw.id === 'string' ? raw.id : null,
91
110
  name,
@@ -93,44 +112,103 @@ export function balanceReport(credits, catalog) {
93
112
  cancel_at_period_end: raw.cancel_at_period_end === true,
94
113
  library_unlimited: raw.library_unlimited === true,
95
114
  monthly_credits: monthly,
96
- monthly_minutes: month?.minutes ?? null,
97
- monthly_time: month?.time ?? null,
115
+ monthly_minutes: month?.voice.minutes ?? null,
116
+ monthly_time: month?.voice.time ?? null,
117
+ monthly_subtitles_minutes: month?.subtitles.minutes ?? null,
118
+ monthly_subtitles_time: month?.subtitles.time ?? null,
98
119
  }
99
120
  const expiring = (Array.isArray(credits?.expiring) ? credits.expiring : [])
100
121
  .filter((lot) => positive(lot?.credits) !== null && day(lot?.expires_at) !== null)
101
122
  .sort((a, b) => Date.parse(a.expires_at) - Date.parse(b.expires_at))
102
123
  .map((lot) => {
103
- const time = byGrade(lot.credits, grades, seconds, 'down')
104
- return { credits: lot.credits, expires_at: lot.expires_at, minutes: time.minutes, time: time.time }
124
+ const time = both(lot.credits)
125
+ return {
126
+ credits: lot.credits,
127
+ expires_at: lot.expires_at,
128
+ minutes: time.voice.minutes,
129
+ time: time.voice.time,
130
+ subtitles_minutes: time.subtitles.minutes,
131
+ subtitles_time: time.subtitles.time,
132
+ }
105
133
  })
106
134
  return {
107
135
  balance,
108
- balance_minutes: left.minutes,
109
- balance_time: left.time,
110
- seconds_per_credit: Object.fromEntries(grades.map((grade) => [grade, seconds[grade]])),
136
+ balance_minutes: left.voice.minutes,
137
+ balance_time: left.voice.time,
138
+ subtitles_minutes: left.subtitles.minutes,
139
+ subtitles_time: left.subtitles.time,
140
+ seconds_per_credit: Object.fromEntries(grades.map((grade) => [grade, times.voice[grade]])),
141
+ subtitles_seconds_per_credit: Object.fromEntries(grades.filter((grade) => times.subtitles[grade]).map((grade) => [grade, times.subtitles[grade]])),
111
142
  plan,
112
143
  expiring,
113
144
  }
114
145
  }
115
146
 
116
- // The same for people: the time left in each grade, the plan and what of the balance expires.
117
- export function balanceLines(report) {
118
- const grades = Object.keys(report.balance_time)
119
- const times = grades.map((grade) => `${report.balance_time[grade]} of ${GRADE_NAMES[grade]}`)
120
- const either = times.length > 1 ? `${times.slice(0, -1).join(', ')} or ${times.at(-1)}` : times[0]
121
- const lines = [`Time left: ${either}`]
147
+ // One amount of a report (the balance, a plan's month, an expiring part) as its minutes and time written of each
148
+ // product, by grade: `voice` from the voice-over's fields, `subtitles` from those of subtitles alone.
149
+ function amount(minutes, time, subtitlesMinutes, subtitlesTime) {
150
+ return {
151
+ subtitles: { minutes: subtitlesMinutes ?? {}, time: subtitlesTime ?? {} },
152
+ voice: { minutes: minutes ?? {}, time: time ?? {} },
153
+ }
154
+ }
155
+
156
+ // An amount in a grade, the person's mode first and, with `other`, the other mode after it where it covers anything
157
+ // (backend ADR 0129): "8 h of Standard subtitles, or 6 h of voice-over". Subtitles with no time of their own leave the
158
+ // voice-over alone, named so. Null where neither has a time.
159
+ function amountText(of, grade, mode, { named = true, other = true } = {}) {
160
+ const order = mode === 'voice' ? ['voice', 'subtitles'] : ['subtitles', 'voice']
161
+ const products = order.filter((product) => of[product].time[grade] !== undefined)
162
+ if (products.length === 0) return null
163
+ const said = (product, withGrade) =>
164
+ `${of[product].time[grade]} of ${withGrade ? `${GRADE_NAMES[grade]} ` : ''}${product === 'voice' ? 'voice-over' : 'subtitles'}`
165
+ const [first, ...rest] = products
166
+ const more = other ? rest.filter((product) => of[product].minutes[grade] > 0) : []
167
+ return [said(first, named), ...more.map((product) => said(product, false))].join(', or ')
168
+ }
169
+
170
+ // Whether an amount covers a whole minute of anything in a grade.
171
+ function covers(of, grade) {
172
+ return of.voice.minutes[grade] > 0 || of.subtitles.minutes[grade] > 0
173
+ }
174
+
175
+ // The same for people (backend ADR 0129): the time left in the person's grade (`grade`, else the cheaper) of what they
176
+ // use (`mode`, subtitles alone until they choose a voice-over), with the other mode in the same grade where it covers
177
+ // anything; then each other grade; the plan and what of the balance expires, told in that grade and mode.
178
+ export function balanceLines(report, grade, mode = 'subtitles') {
179
+ const listed = Object.keys(report.balance_time)
180
+ const grades = listed.includes(grade) ? [grade, ...listed.filter((name) => name !== grade)] : listed
181
+ const main = grades[0]
182
+ const left = amount(report.balance_minutes, report.balance_time, report.subtitles_minutes, report.subtitles_time)
183
+ const lines = [`Time left: ${amountText(left, main, mode)}`]
184
+ for (const other of grades.slice(1)) lines.push(`In ${GRADE_NAMES[other]}: ${amountText(left, other, mode, { named: false })}`)
122
185
  const { plan } = report
123
186
  if (plan) {
124
187
  const parts = [plan.name]
125
- const first = grades[0]
126
- if (plan.monthly_time) parts.push(`${plan.monthly_time[first]} of ${GRADE_NAMES[first]} a month`)
188
+ const month = amount(plan.monthly_minutes, plan.monthly_time, plan.monthly_subtitles_minutes, plan.monthly_subtitles_time)
189
+ const monthly = amountText(month, main, mode, { other: false })
190
+ if (monthly) parts.push(`${monthly} a month`)
127
191
  if (plan.renews_at) parts.push(`${plan.cancel_at_period_end ? 'ends' : 'renews'} ${plan.renews_at.slice(0, 10)}`)
128
192
  if (plan.library_unlimited) parts.push('Library included')
129
193
  lines.push(`Plan: ${parts.join(', ')}`)
130
194
  }
131
195
  for (const lot of report.expiring) {
132
- const first = grades[0]
133
- if (lot.minutes[first] > 0) lines.push(`${lot.time[first]} of ${GRADE_NAMES[first]} expires on ${lot.expires_at.slice(0, 10)}`)
196
+ const part = amount(lot.minutes, lot.time, lot.subtitles_minutes, lot.subtitles_time)
197
+ if (covers(part, main)) lines.push(`${amountText(part, main, mode, { other: false })} expires on ${lot.expires_at.slice(0, 10)}`)
134
198
  }
135
199
  return lines
136
200
  }
201
+
202
+ // A balance in one grade as an assistant hears it, subtitles alone first where they have a time (backend ADR 0129, as
203
+ // Vocnu's own MCP server says it): "8 h of subtitles or 6 h of voice-over".
204
+ export function gradeBalance(credits, grade, times) {
205
+ const voice = `${duration(minutesOf(credits, times.voice[grade], 'down'))} of voice-over`
206
+ const seconds = times.subtitles[grade]
207
+ return seconds ? `${duration(minutesOf(credits, seconds, 'down'))} of subtitles or ${voice}` : voice
208
+ }
209
+
210
+ // The balance as one time for a sentence, in the grade and mode of the person (login) or of a job: "6 h 40 min of
211
+ // Standard subtitles", the voice-over's where subtitles alone have no time.
212
+ export function balanceTime(credits, grade, mode, times) {
213
+ return productTime(credits, grade, mode === 'voice', times, 'down') ?? productTime(credits, grade, true, times, 'down')
214
+ }
package/src/mcp.js CHANGED
@@ -1,8 +1,9 @@
1
1
  // The Vocnu MCP server (stdio): lets Claude and other AI assistants upload a local file, show its price, start a
2
2
  // translation, follow it, save the results and share them with a link. Spending the user's time is a separate tool,
3
3
  // so the assistant can confirm the price with the user first. People hear time, never credits (backend ADR 0122): every
4
- // balance and price comes as time of a grade (`*_time`) beside the credits Vocnu counts in. stdout carries the
5
- // protocol only.
4
+ // balance and price comes as time (`*_time`) of what it makes in a grade, subtitles alone in their own time (ADR 0129),
5
+ // beside the credits Vocnu counts in. Standard is asked for by its name, `standard`, or its id, `economy`, which results
6
+ // name it by. stdout carries the protocol only.
6
7
  import { homedir } from 'node:os'
7
8
  import { join, resolve } from 'node:path'
8
9
 
@@ -13,9 +14,11 @@ import { z } from 'zod'
13
14
  import { VocnuApi } from './api.js'
14
15
  import { loadConfig } from './config.js'
15
16
  import { formatTimeLeft, secondsLeft } from './estimate.js'
16
- import { balanceReport, catalogOf, costGrade, duration, gradeTime, minutesOf, secondsPerCredit } from './hours.js'
17
+ import { currentGrade, gradeFrom, gradeMakes, jobGrade, modeFrom, preferencesOf, preferredGrade } from './grades.js'
18
+ import { balanceLines, balanceReport, catalogOf, gradeBalance, productTime, timesOf } from './hours.js'
17
19
  import {
18
- AUDIO_FORMATS, defaultVideoFormat, GRADES, gradeQuote, isVideo, OUTPUTS, productsFor, quotedCredits, VIDEO_FORMATS,
20
+ AUDIO_FORMATS, defaultVideoFormat, GRADE_ARGUMENTS, GRADE_NAMES, GRADES, gradeQuote, isVideo, OUTPUTS, productsFor,
21
+ quotedCredits, VIDEO_FORMATS,
19
22
  } from './media.js'
20
23
  import { VERSION } from './version.js'
21
24
 
@@ -38,16 +41,17 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
38
41
 
39
42
  tool('vocnu_languages', {
40
43
  annotations: { readOnlyHint: true },
41
- description: 'Languages Vocnu translates into (code and name); some take subtitles only. voiceover_grades: the '
42
- + 'grades a voice-over into the language can be made in now, "premium" and, where offered, "standard" and '
43
- + '"economy". Subtitles alone come in "premium" or, where offered (price_time_by_grade of an upload), '
44
- + '"economy", into any language.',
44
+ description: 'Languages Vocnu translates into (code and name); some take subtitles only. Subtitles alone come '
45
+ + 'in Standard where offered (price_time_by_grade of an upload) or Premium, into any language. '
46
+ + 'voiceover_grades: the grades a voice-over into the language can be made in now, by their ids: "economy" '
47
+ + 'for Standard where offered, and "premium".',
45
48
  title: 'Vocnu languages',
46
49
  }, async () => {
47
50
  const catalog = await api.catalog()
51
+ // Only the grades on offer, whatever an older Vocnu still lists (backend ADR 0126).
48
52
  return (catalog.languages ?? []).map((l) => ({
49
53
  code: l.code, name: l.name, voiceover: l.voiceover !== false,
50
- ...(l.voiceover_grades ? { voiceover_grades: l.voiceover_grades } : {}),
54
+ ...(l.voiceover_grades ? { voiceover_grades: l.voiceover_grades.filter((grade) => GRADES.includes(grade)) } : {}),
51
55
  }))
52
56
  })
53
57
 
@@ -57,38 +61,51 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
57
61
  + 'sounds, whether it is the default of its type, and a short sample (MP3) the user can listen to. Pass the '
58
62
  + 'chosen id as voice_id to vocnu_start_job, with the same grade: each grade has voices of its own.',
59
63
  inputSchema: {
60
- grade: z.enum(GRADES).optional().describe('Whose voices: "premium" (default), "standard" or "economy"'),
64
+ grade: z.enum(GRADE_ARGUMENTS).optional().describe('Whose voices: "standard" or "premium" (default: the user\'s '
65
+ + 'grade, the one vocnu_start_job takes without a grade, where it reads the language, else "premium"). '
66
+ + 'Standard\'s id, "economy", is taken too'),
61
67
  language: z.string().describe('Language code, e.g. lt, en, de (see vocnu_languages)'),
62
68
  },
63
69
  title: 'Vocnu voices',
64
- }, async ({ grade, language }) => (await api.voices(language, grade)).map((v) => ({
65
- default: v.default, gender: v.gender, grade: v.grade, id: v.id, name: v.name, sample_url: v.sample_url, traits: v.traits,
66
- })))
70
+ }, async ({ grade, language }) => {
71
+ const whose = grade === undefined ? await jobGrade(api, await catalogOf(api), 'audio', language) : currentGrade(grade)
72
+ return (await api.voices(language, whose)).map((v) => ({
73
+ default: v.default, gender: v.gender, grade: v.grade, id: v.id, name: v.name, sample_url: v.sample_url, traits: v.traits,
74
+ }))
75
+ })
67
76
 
68
77
  tool('vocnu_credits', {
69
78
  annotations: { readOnlyHint: true },
70
- description: "How much Vocnu time the user has left: balance_time, the time of voice-over their balance covers in "
71
- + 'each grade on offer, as they should hear it ("4 h 20 min" of Premium; Standard lasts twice as long, Economy '
72
- + 'four times), and balance_minutes, the same in whole minutes. plan: the monthly plan when there is one (null '
73
- + 'otherwise), with when it renews or, cancelled, ends, the time each month brings and library_unlimited, true '
74
- + 'only where the plan makes the Vocnu Library unlimited. expiring: parts of the balance that expire, soonest '
75
- + 'first, with their time. balance, monthly_credits and each expiring part\'s credits are the same in credits, '
76
- + 'Vocnu\'s internal unit: tell the user time, never credits.',
79
+ description: 'How much Vocnu time the user has left. time_left is what to tell them: the time of what they make '
80
+ + '(subtitles alone unless they chose a voice-over in Vocnu, mode) in their grade, with the other in the same '
81
+ + 'grade ("8 h of Standard subtitles, or 6 h of voice-over"). In each grade on offer, by id ("economy" is '
82
+ + 'Standard): subtitles_time, the time of subtitles alone their balance covers, and balance_time, of voice-over; '
83
+ + 'subtitles_minutes and balance_minutes, the same in whole minutes. plan: the monthly plan when there is one '
84
+ + '(null otherwise), with when it renews or, cancelled, ends, the time each month brings (monthly_subtitles_time, '
85
+ + 'monthly_time) and library_unlimited, true only where the plan makes the Vocnu Library unlimited. expiring: '
86
+ + 'parts of the balance that expire, soonest first, with their time. balance, monthly_credits and each expiring '
87
+ + 'part\'s credits are the same in credits, Vocnu\'s internal unit: tell the user time, never credits.',
77
88
  title: 'Vocnu time left',
78
89
  }, async () => {
79
- const [credits, catalog] = await Promise.all([api.credits(), catalogOf(api)])
80
- return balanceReport(credits, catalog)
90
+ const [credits, catalog, preferences] = await Promise.all([api.credits(), catalogOf(api), preferencesOf(api)])
91
+ const report = balanceReport(credits, catalog)
92
+ const mode = modeFrom(preferences)
93
+ const [left] = balanceLines(report, gradeFrom(preferences, catalog), mode)
94
+ return { time_left: left.replace(/^Time left: /, ''), mode, ...report }
81
95
  })
82
96
 
83
97
  tool('vocnu_upload_media', {
84
98
  description: 'Upload a local video or audio file (up to 10 GB) to Vocnu, wait until it is analysed and return its '
85
99
  + 'source_id, length and the time of the user\'s balance each output uses, as they should hear it: price_time '
86
- + 'in Premium, and price_time_by_grade in each grade offered ("12 min of Premium"; a voice-over is told in its '
87
- + 'own grade, subtitles alone in Standard\'s or Economy\'s time; sdh_extra is what SDH adds to a voice-over, '
88
- + 'sdh_extra_with_subtitles to subtitles alone), with balance_time, the time left in each grade. Standard: '
89
- + 'simpler voices and translation, the time lasts twice as long, its subtitles alone are Premium\'s at '
90
- + 'Premium\'s price; Economy: where the time lasts longest, a voice-over or subtitles alone by a plain '
91
- + 'synthetic voice reading a quick translation. price_credits, price_credits_by_grade (with each grade\'s '
100
+ + 'in grade, the user\'s grade, which vocnu_start_job takes when it names none ("economy", Standard\'s id, '
101
+ + 'unless they chose Premium), and price_time_by_grade in each grade offered. Each output is told in the time '
102
+ + 'of what it makes in its grade: subtitles alone in subtitles ("12 min of Standard subtitles"), the others in '
103
+ + 'voice-over ("24 min of Standard voice-over"); sdh_extra is what SDH adds to a voice-over, '
104
+ + 'sdh_extra_with_subtitles to subtitles alone. balance_time: the time left in each grade, of subtitles alone '
105
+ + 'and of voice-over. Subtitles alone last longest, so offer them first. Standard: the time lasts several '
106
+ + 'times as long as in Premium, a quick translation, read by a plain synthetic voice in a voice-over; Premium: '
107
+ + 'natural voices and a careful translation. '
108
+ + 'price_credits, price_credits_by_grade (with each grade\'s '
92
109
  + 'credits_per_minute) and balance are the same in credits, Vocnu\'s internal unit: tell the user time, never '
93
110
  + 'credits. Nothing is used until vocnu_start_job. '
94
111
  + 'captions_only is true for a video nobody speaks in whose story is told in captions burned into the picture: '
@@ -100,9 +117,9 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
100
117
  const uploaded = await api.upload(file)
101
118
  const source = await api.waitForSource(uploaded.id)
102
119
  const [{ balance }, catalog] = await Promise.all([api.credits(), catalogOf(api)])
103
- const seconds = secondsPerCredit(catalog)
120
+ const times = timesOf(catalog, source.quote)
104
121
  const prices = (quote) => ({
105
- // The grade's rates a minute, such as 0.5 in Economy (null from a server before them).
122
+ // The grade's rates a minute, such as 0.5 for Standard's voice-over (null from a server before them).
106
123
  credits_per_minute: quote.credits_per_minute ?? null,
107
124
  audio: quote.options.voiceover_audio,
108
125
  subtitles: quote.options.subtitles,
@@ -115,40 +132,42 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
115
132
  // What SDH subtitles add to any output (null: not offered).
116
133
  sdh_extra: quote.options.sdh ?? null,
117
134
  })
118
- // The same as time of the grade (a voice-over's own, subtitles alone in Standard's or Economy's), rounded up.
119
- const times = (quote, grade) => {
120
- const voiced = (credits) => (typeof credits === 'number' ? gradeTime(credits, grade, seconds, 'up') : null)
121
- const subtitled = (credits) =>
122
- (typeof credits === 'number' ? gradeTime(credits, costGrade(grade, false), seconds, 'up') : null)
135
+ // The same as time of what each output makes in the grade, rounded up (backend ADR 0122, 0126, 0129): subtitles
136
+ // alone, and SDH added to them, in subtitles' time (null where nobody gave their rate), never a voice-over's.
137
+ const timed = (quote, grade) => {
138
+ const told = (credits, voiced) => (typeof credits === 'number' ? productTime(credits, grade, voiced, times, 'up') : null)
123
139
  return {
124
- audio: voiced(quote.options.voiceover_audio),
125
- subtitles: subtitled(quote.options.subtitles),
126
- video: source.has_video ? voiced(quotedCredits(quote, 'video', defaultVideoFormat(file))) : null,
140
+ audio: told(quote.options.voiceover_audio, true),
141
+ subtitles: told(quote.options.subtitles, false),
142
+ video: source.has_video ? told(quotedCredits(quote, 'video', defaultVideoFormat(file)), true) : null,
127
143
  video_by_format: source.has_video
128
- ? Object.fromEntries(VIDEO_FORMATS.map((format) => [format, voiced(quotedCredits(quote, 'video', format))]))
144
+ ? Object.fromEntries(VIDEO_FORMATS.map((format) => [format, told(quotedCredits(quote, 'video', format), true)]))
129
145
  : null,
130
- video_with_burned_subtitles: source.has_video ? voiced(quote.options.voiceover_video_burned_subtitles) : null,
131
- sdh_extra: voiced(quote.options.sdh),
132
- sdh_extra_with_subtitles: subtitled(quote.options.sdh),
146
+ video_with_burned_subtitles: source.has_video ? told(quote.options.voiceover_video_burned_subtitles, true) : null,
147
+ sdh_extra: told(quote.options.sdh, true),
148
+ sdh_extra_with_subtitles: told(quote.options.sdh, false),
133
149
  }
134
150
  }
135
- // A server before the grades prices Premium only.
136
- const offered = Object.keys(source.quote.grades ?? { premium: true })
137
- // The time left in each grade a price is told in, so the two compare: the grades offered, and Standard's or
138
- // Economy's for subtitles alone.
139
- const told = GRADES.filter((grade) => offered.some((each) => each === grade || costGrade(each, false) === grade))
151
+ // The grades offered, Standard (`economy`) first: a server before the grades prices Premium only, and the old
152
+ // `standard` an older one still quotes is not offered (backend ADR 0126). The user's own grade, where this upload is priced in it, is the
153
+ // one a job takes without a grade.
154
+ const quoted = Object.keys(source.quote.grades ?? { premium: true })
155
+ const offered = GRADES.filter((grade) => quoted.includes(grade))
156
+ const preferred = await preferredGrade(api, catalog)
157
+ const grade = offered.includes(preferred) ? preferred : 'premium'
140
158
  return {
141
159
  balance,
142
160
  balance_time: typeof balance === 'number'
143
- ? Object.fromEntries(told.map((grade) => [grade, duration(minutesOf(balance, seconds[grade], 'down'))]))
161
+ ? Object.fromEntries(offered.map((name) => [name, gradeBalance(balance, name, times)]))
144
162
  : null,
145
163
  captions_only: source.captions_only === true,
146
164
  duration_seconds: source.duration_seconds,
147
165
  has_video: source.has_video,
148
- price_credits: prices(source.quote),
149
- price_credits_by_grade: Object.fromEntries(offered.map((grade) => [grade, prices(gradeQuote(source.quote, grade))])),
150
- price_time: times(source.quote, 'premium'),
151
- price_time_by_grade: Object.fromEntries(offered.map((grade) => [grade, times(gradeQuote(source.quote, grade), grade)])),
166
+ grade,
167
+ price_credits: prices(gradeQuote(source.quote, grade)),
168
+ price_credits_by_grade: Object.fromEntries(offered.map((name) => [name, prices(gradeQuote(source.quote, name))])),
169
+ price_time: timed(gradeQuote(source.quote, grade), grade),
170
+ price_time_by_grade: Object.fromEntries(offered.map((name) => [name, timed(gradeQuote(source.quote, name), name)])),
152
171
  source_id: source.id,
153
172
  suggested_video_format: isVideo(file) ? defaultVideoFormat(file) : null,
154
173
  title: source.title,
@@ -158,22 +177,24 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
158
177
  tool('vocnu_start_job', {
159
178
  description: 'Start translating an uploaded file (source_id from vocnu_upload_media). Uses the quoted time of '
160
179
  + 'the user\'s balance (given back if the job fails or is cancelled): confirm the price with the user before '
161
- + 'calling; balance_after_time is the time left after it, in the grade the job is told in. output "video" '
180
+ + 'calling; balance_after_time is the time left after it, of what the job makes in its grade. output "video" '
162
181
  + 'is the video with the voice-over, "audio" the voice-over audio, "subtitles" subtitles only; every output '
163
182
  + 'also includes subtitles. sdh adds SDH subtitles (sound descriptions, speaker names, songs) for deaf and '
164
183
  + 'hard-of-hearing viewers to any output, at the sdh_extra price. Subtitles may be in the spoken language '
165
184
  + '(target_language = source_language, e.g. German SDH of a German film); a voice-over may not, except for a '
166
- + 'captions_only upload, whose captions the narrator then reads as written. grade "standard" makes the '
167
- + 'voice-over with simpler voices and translation, the time lasting twice as long; "economy" makes a '
168
- + 'voice-over or subtitles alone where the time lasts longest, a plain synthetic voice reading a quick '
169
- + 'translation; each where offered (see price_time_by_grade and vocnu_languages); the price to confirm is then '
170
- + 'that grade\'s.',
185
+ + 'captions_only upload, whose captions the narrator then reads as written. Without grade the job takes the '
186
+ + 'user\'s grade, the grade of vocnu_upload_media (Standard unless they chose Premium), at price_time; '
187
+ + '"standard" makes subtitles alone or a voice-over where the time lasts longest (several times as long as in '
188
+ + 'Premium), a quick translation, read by a plain synthetic voice in a voice-over, where offered (see '
189
+ + 'price_time_by_grade and vocnu_languages), and "premium" natural voices and a careful translation. Confirm '
190
+ + 'the price of the grade the job takes.',
171
191
  inputSchema: {
172
192
  audio_format: z.enum(AUDIO_FORMATS).optional().describe('Voice-over audio format (default m4a)'),
173
193
  burn_subtitles: z.boolean().optional().describe('Burn the subtitles into the picture (video only)'),
174
- grade: z.enum(GRADES).optional().describe('"premium" (default), "standard" or "economy". Standard is for a '
175
- + 'voice-over (its subtitles alone are Premium\'s); Economy makes subtitles alone too, in its own '
176
- + 'translation. A voice_id must be one of the grade\'s voices (vocnu_voices with the grade)'),
194
+ grade: z.enum(GRADE_ARGUMENTS).optional().describe('"standard" or "premium" (default: the user\'s grade, the '
195
+ + 'grade of vocnu_upload_media). Standard makes subtitles alone too, in its own translation; results name it '
196
+ + 'by its id, "economy", which is taken too. A voice_id must be one of the grade\'s voices (vocnu_voices with '
197
+ + 'the same grade, or without one for the default)'),
177
198
  original_level: z.number().int().min(0).max(100).optional()
178
199
  .describe('How loud the original sound stays under the voice, in percent: 0 silent, 100 unchanged '
179
200
  + '(default: the level recommended for the upload from how loud its own speech is, else 40). Voice-over '
@@ -199,6 +220,16 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
199
220
  }, async (input) => {
200
221
  const chosen = input.video_formats ?? [input.video_format ?? 'mp4']
201
222
  const videoFormats = VIDEO_FORMATS.filter((format) => chosen.includes(format))
223
+ const catalog = await catalogOf(api)
224
+ // Without a grade, the user's own (backend ADR 0126). Where it does not make this output into this language,
225
+ // nothing starts: the price confirmed was its own, and Premium's is dearer.
226
+ const grade = input.grade === undefined ? await preferredGrade(api, catalog) : currentGrade(input.grade)
227
+ if (input.grade === undefined && !gradeMakes(catalog, grade, input.output, input.target_language)) {
228
+ const what = input.output === 'subtitles' ? 'subtitles alone' : `a voice-over in ${input.target_language}`
229
+ throw new Error(`${GRADE_NAMES[grade]} does not make ${what} yet; Premium does. Tell the user Premium's price `
230
+ + '(price_time_by_grade.premium of vocnu_upload_media) and, once they agree, call again with grade "premium". '
231
+ + 'Nothing was used.')
232
+ }
202
233
  const created = await api.createJob({
203
234
  audio_format: input.audio_format ?? 'm4a',
204
235
  products: productsFor(input.output, input.burn_subtitles, input.sdh === true),
@@ -211,15 +242,15 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
211
242
  ...(input.voice_id ? { voice_id: input.voice_id } : {}),
212
243
  ...(input.original_level === undefined || input.original_off ? {} : { original_level: input.original_level }),
213
244
  ...(input.original_off ? { original_off: true } : {}),
214
- ...(input.grade ? { grade: input.grade } : {}),
245
+ // A job that names no grade is Premium's on every server, so Premium's names none.
246
+ ...(grade === 'premium' ? {} : { grade }),
215
247
  })
216
- // The time left told in the grade the job's cost is: its own for a voice-over, Standard's or Economy's for subtitles.
217
- const told = costGrade(input.grade ?? 'premium', input.output !== 'subtitles')
218
- const seconds = secondsPerCredit(await catalogOf(api))
248
+ // The time left told of what the job makes in its grade, as its price was (backend ADR 0129).
249
+ const told = GRADES.includes(created.job.grade) ? created.job.grade : grade
219
250
  return {
220
251
  balance_after: created.credit_balance,
221
252
  balance_after_time: typeof created.credit_balance === 'number'
222
- ? gradeTime(created.credit_balance, told, seconds, 'down')
253
+ ? productTime(created.credit_balance, told, input.output !== 'subtitles', timesOf(catalog), 'down')
223
254
  : null,
224
255
  grade: created.job.grade, job_id: created.job.id, status: created.job.status,
225
256
  }
package/src/media.js CHANGED
@@ -10,12 +10,18 @@ const TYPES = {
10
10
  export const VIDEO_FORMATS = ['mp4', 'mkv', 'mov', 'webm', 'avi']
11
11
  export const AUDIO_FORMATS = ['m4a', 'mp3', 'wav', 'flac', 'ogg']
12
12
  export const OUTPUTS = ['video', 'audio', 'subtitles']
13
- // The grades (backend ADR 0080, 0083): Premium, the default, Standard, a voice-over for half the credits, and Economy,
14
- // the cheapest, at half a credit a minute of a voice-over or of subtitles alone. Subtitles alone are Premium's
15
- // translation in Premium and Standard, Economy's own in Economy.
16
- export const GRADES = ['premium', 'standard', 'economy']
17
- export const SUBTITLE_GRADES = ['premium', 'economy']
18
- export const GRADE_NAMES = { premium: 'Premium', standard: 'Standard', economy: 'Economy' }
13
+ // The grades on offer, cheaper first (backend ADR 0080, 0083, 0126, 0127): Standard, whose id is `economy`, the default
14
+ // where Vocnu offers it, and Premium. Both make a voice-over and subtitles alone, each at its own rate as Vocnu's
15
+ // catalog says. People and scripts ask for Standard by its name, `standard`, or by its id; both are `economy`. The old
16
+ // grade called `standard` was retired (ADR 0126), and its name stays for the jobs made in it.
17
+ export const GRADES = ['economy', 'premium']
18
+ export const SUCCESSORS = { standard: 'economy' }
19
+ // What `--grade` and the MCP tools take: Standard by its name first, then Premium, and Standard's id, which results
20
+ // name it by.
21
+ export const GRADE_ARGUMENTS = ['standard', 'premium', 'economy']
22
+ // The argument that asks for each grade, as the help and the hints write it.
23
+ export const GRADE_ARGUMENT = { economy: 'standard', premium: 'premium' }
24
+ export const GRADE_NAMES = { premium: 'Premium', standard: 'Standard', economy: 'Standard' }
19
25
 
20
26
  export function contentType(path) {
21
27
  return TYPES[extname(path).toLowerCase()] ?? null