vocnu 0.7.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
@@ -19,29 +19,43 @@ or set `VOCNU_TOKEN` in the environment.
19
19
  npx vocnu translate film.mkv --to lt
20
20
  ```
21
21
 
22
- Vocnu uploads the file (up to 10 GB), shows the price in credits and asks before it starts, follows the job with its
23
- progress and time left, and saves the results next to the file. Options:
22
+ Vocnu uploads the file (up to 10 GB), shows how much of your time it uses and how much you have left, asks before it
23
+ starts, follows the job with its progress, and saves the results next to the file. Options:
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: a voice-over for half the credits, with simpler voices and translation (its subtitles alone are Premium's); or Economy, the lowest price: 0.5 credits a minute of a voice-over or of subtitles alone, 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 |
33
33
  | `--burn-subtitles` | subtitles burned into the picture |
34
34
  | `--original-level <0-100>` | how loud the original sound stays under the voice, in percent (default: the level Vocnu recommends for the video from how loud its own speech is, else 40; 0 silences it, 100 leaves it as it is); it comes back to full volume only in long pauses in the narration |
35
35
  | `--original-off` | the original sound turned off: the voice-over alone, with silence between its lines (no original voices, music or sound effects) |
36
- | `--sdh` | SDH subtitles as well (sounds, speaker names and songs for deaf and hard-of-hearing viewers), one more credit per minute; with `--output subtitles` they may be in the spoken language (`--from de --to de`) |
36
+ | `--sdh` | SDH subtitles as well (sounds, speaker names and songs for deaf and hard-of-hearing viewers), which adds to the time the job uses; with `--output subtitles` they may be in the spoken language (`--from de --to de`) |
37
37
  | `--out <dir>` | where the results go |
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:
43
- `vocnu credits`, `vocnu languages`, `vocnu jobs`, `vocnu status <job>`, `vocnu download <job>`,
44
- `vocnu cancel <job>`, `vocnu logout`.
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
+ `vocnu languages`, `vocnu jobs`, `vocnu status <job>`, `vocnu download <job>`, `vocnu cancel <job>`, `vocnu logout`.
44
+
45
+ ## Your time
46
+
47
+ ```sh
48
+ npx vocnu time # time left of subtitles and voice-over, your plan and what expires
49
+ npx vocnu time --json # the same for scripts
50
+ ```
51
+
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.
45
59
 
46
60
  ## Share the results
47
61
 
@@ -76,12 +90,15 @@ Claude Desktop (`claude_desktop_config.json`) and other MCP clients:
76
90
  ```
77
91
 
78
92
  Then ask, for example, “Dub ~/Videos/film.mkv into Lithuanian with Vocnu”. The assistant uploads the file
79
- (`vocnu_upload_media`), tells you the price of each grade, starts the job only after you agree (`vocnu_start_job`,
80
- 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
81
96
  (`vocnu_job_status`) and saves the files (`vocnu_download_results`) or gives you a link to send
82
97
  (`vocnu_share_job`, turned off with `vocnu_revoke_share`). Also: `vocnu_languages`, `vocnu_voices` (the voices of a
83
- language and grade with their samples, for `vocnu_start_job`'s `voice_id`), `vocnu_credits`, `vocnu_list_jobs`,
84
- `vocnu_cancel_job`.
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.
85
102
 
86
103
  ## Development
87
104
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vocnu",
3
- "version": "0.7.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,9 +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 { currentGrade, gradeFrom, gradeMakes, jobGrade, modeFrom, preferencesOf, preferredGrade } from './grades.js'
12
+ import { balanceLines, balanceReport, balanceTime, catalogOf, offeredGrades, productTime, timesOf } from './hours.js'
11
13
  import {
12
- AUDIO_FORMATS, contentType, defaultVideoFormat, GRADE_NAMES, GRADES, gradeQuote, isVideo, OUTPUTS, productsFor, quotedCredits,
13
- 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,
14
16
  } from './media.js'
15
17
  import { VERSION } from './version.js'
16
18
 
@@ -21,16 +23,19 @@ const HELP = `Vocnu ${VERSION}: AI voice-over and subtitles for your videos (htt
21
23
  Usage:
22
24
  vocnu login [--token <token>] Save an API token (app.vocnu.com → Settings → API & MCP)
23
25
  vocnu logout Forget the saved token
24
- vocnu credits Your credit balance
26
+ vocnu time [--json] Your time left of subtitles and voice-over in each grade, your plan
27
+ and what expires
25
28
  vocnu languages Languages you can translate into
26
29
  vocnu voices <lang> Voices of a language, each with a short sample to listen to
27
- --grade premium|standard|economy Another grade's voices instead of Premium's
30
+ --grade standard|premium Whose voices (default: your grade's)
28
31
  vocnu translate <file> --to <lang> Upload, see the price, translate and download the results
29
- --output video|audio|subtitles What you get (default: video for a video file, else audio)
30
- --grade premium|standard|economy Premium (default); Standard: a voice-over for half the credits, with
31
- simpler voices and translation; or Economy, the lowest price: 0.5 credits
32
- a minute of a voice-over or of subtitles alone, a plain synthetic voice
33
- reading a quick translation (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)
34
39
  --from <lang> Spoken language (default: detected)
35
40
  --voice male|female|<voice id> A voice type, or a voice from \`vocnu voices\` (default: male)
36
41
  --format mp4|mkv|mov|webm|avi Video file format, or several: mp4,mkv (default: the upload's, else mp4)
@@ -49,7 +54,7 @@ Usage:
49
54
  vocnu status <job> Progress, time left and files of a job
50
55
  vocnu download <job> [--out <dir>] Save the files of a finished job
51
56
  vocnu share <job> [--revoke] A link anyone can open to play and download the files
52
- vocnu cancel <job> Cancel a job (its credits are refunded)
57
+ vocnu cancel <job> Cancel a job (the time it held is given back)
53
58
  vocnu mcp Run the Vocnu MCP server (for Claude and other assistants)
54
59
 
55
60
  The token can also come from VOCNU_TOKEN.`
@@ -80,15 +85,14 @@ export async function main(argv, { env = process.env, out = process.stdout, err
80
85
  await forgetCredentials(env)
81
86
  print('Signed out: the saved token is gone (revoke it in the app if it may have leaked).')
82
87
  return 0
83
- case 'credits': {
84
- const { balance } = await api.credits()
85
- print(`${balance} credits`)
86
- return 0
87
- }
88
+ // `credits`, its name before Vocnu told time (backend ADR 0122), stays for scripts that call it.
89
+ case 'time':
90
+ case 'credits':
91
+ return await timeLeft(rest, { api, print })
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':
@@ -101,7 +105,7 @@ export async function main(argv, { env = process.env, out = process.stdout, err
101
105
  return await share(rest, { api, print })
102
106
  case 'cancel': {
103
107
  const job = await api.cancel(required(rest[0], 'job id'))
104
- print(`Cancelled ${job.id}; its credits were refunded.`)
108
+ print(`Cancelled ${job.id}; the time it held was given back.`)
105
109
  return 0
106
110
  }
107
111
  default:
@@ -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,8 +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()
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))
148
160
  const path = await saveCredentials({ token, url }, env)
149
- print(`Signed in (${balance} credits). Token saved in ${path}.`)
161
+ print(`Signed in (${left} left). Token saved in ${path}.`)
162
+ return 0
163
+ }
164
+
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.
167
+ async function timeLeft(args, { api, print }) {
168
+ const { values } = parse(args, { json: { type: 'boolean' } })
169
+ const [answer, catalog] = await Promise.all([api.credits(), catalogOf(api)])
170
+ const report = balanceReport(answer, catalog)
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)
150
177
  return 0
151
178
  }
152
179
 
@@ -158,11 +185,18 @@ async function languages(api, print) {
158
185
  return 0
159
186
  }
160
187
 
161
- 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 }) {
162
190
  const { positionals, values } = parse(args, { grade: { type: 'string' } })
163
191
  const language = required(positionals[0], 'language code')
164
- checkGrade(values.grade)
165
- 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)) {
166
200
  const about = [voice.gender, ...(voice.traits ?? [])].join(', ')
167
201
  print(`${voice.id.padEnd(24)} ${voice.name} (${about})${voice.default ? ', default' : ''}`)
168
202
  print(`${''.padEnd(24)} ${voice.sample_url}`)
@@ -200,14 +234,7 @@ async function translate(args, { api, err, out, print }) {
200
234
  const originalLevel = values['original-level']
201
235
  // Or none of the original at all, between the lines too (backend ADR 0067).
202
236
  const originalOff = values['original-off'] === true
203
- // Premium unless asked (backend ADR 0080); a job that names none is Premium's on every server.
204
- const grade = values.grade ?? 'premium'
205
- checkGrade(values.grade)
206
- // Subtitles alone come in Premium or in Economy's own translation; Standard's would be Premium's.
207
- if (output === 'subtitles' && !SUBTITLE_GRADES.includes(grade)) {
208
- const names = listed(SUBTITLE_GRADES.map((name) => GRADE_NAMES[name]))
209
- throw new UsageError(`--grade ${grade} is for a voice-over: subtitles alone come in ${names}.`)
210
- }
237
+ const asked = askedGrade(values.grade)
211
238
  if (!OUTPUTS.includes(output)) throw new UsageError(`--output is one of ${OUTPUTS.join(', ')}.`)
212
239
  if (!videoFormats) throw new UsageError(`--format is one or more of ${VIDEO_FORMATS.join(', ')}, separated by commas.`)
213
240
  if (!AUDIO_FORMATS.includes(audioFormat)) throw new UsageError(`--audio-format is one of ${AUDIO_FORMATS.join(', ')}.`)
@@ -220,9 +247,34 @@ async function translate(args, { api, err, out, print }) {
220
247
  if (originalOff && originalLevel !== undefined) throw new UsageError('--original-off leaves no original to set a level for: use one of them.')
221
248
  if (output === 'video' && !isVideo(path)) throw new UsageError('This is an audio file: use --output audio or subtitles.')
222
249
  if (!contentType(path)) throw new UsageError('Vocnu takes video and audio files (MP4, MOV, MKV, WebM, MP3, M4A, WAV...).')
223
- if (voice !== voiceType && !(await api.voices(target, values.grade)).some((candidate) => candidate.id === voice)) {
224
- const listing = `vocnu voices ${target}${values.grade ? ` --grade ${grade}` : ''}`
225
- 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
226
278
  }
227
279
  const { size } = await stat(path)
228
280
 
@@ -233,21 +285,32 @@ async function translate(args, { api, err, out, print }) {
233
285
  source = await api.waitForSource(source.id)
234
286
  progress.done(`Ready: ${source.title ?? basename(path)}, ${formatDuration(source.duration_seconds)}`)
235
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
+ }
236
295
  const prices = gradeQuote(source.quote, grade)
237
- if (!prices) throw new VocnuError(`${GRADE_NAMES[grade]} is not available yet: use --grade premium. Nothing was charged.`)
238
296
  const choice = [output, videoFormats, values['burn-subtitles'], values.sdh]
239
297
  const credits = quotedCredits(prices, ...choice)
240
298
  const { balance } = await api.credits()
241
- // The grade is named once the server prices grades; a server before them makes only Premium.
242
- const graded = source.quote.grades ? `, ${GRADE_NAMES[grade]}` : ''
243
- print(`Price: ${credits} credits (${source.quote.minutes} min${graded}). Balance: ${balance} credits.`)
244
- // Short of credits in the grade asked, what the balance covers in a cheaper grade says so.
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'
303
+ const fileMinutes = source.quote.minutes
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.`)
308
+ // Short of time in the grade asked, the cheaper grades the balance covers say so.
245
309
  if (credits > balance) {
246
- 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 })
247
311
  if (cheaper.length > 0) {
248
- const offers = cheaper.map(({ credits: price, grade: name }, index) =>
249
- `in ${GRADE_NAMES[name]} ${index === 0 ? 'it costs ' : ''}${price} (add --grade ${name})`)
250
- print(`Not enough credits for ${GRADE_NAMES[grade]}: ${offers.join(', ')}.`)
312
+ const offers = cheaper.map((name) => `${GRADE_NAMES[name]} (add --grade ${GRADE_ARGUMENT[name]})`)
313
+ print(`Not enough time left for ${GRADE_NAMES[grade]}: it fits in ${offers.join(' or ')}.`)
251
314
  }
252
315
  }
253
316
  if (!values.yes) {
@@ -270,14 +333,16 @@ async function translate(args, { api, err, out, print }) {
270
333
  ...(voice === voiceType ? {} : { voice_id: voice }),
271
334
  ...(originalLevel === undefined ? {} : { original_level: Number(originalLevel) }),
272
335
  ...(originalOff ? { original_off: true } : {}),
273
- ...(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 }),
274
338
  })
275
- print(`Started job ${created.job.id} (${created.credit_balance} credits 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).`)
276
341
  if (values['no-wait']) return 0
277
342
 
278
343
  const job = await follow(api, created.job.id, progress)
279
344
  if (job.status !== 'completed') {
280
- err.write(`Job ${job.status}: ${job.error?.message ?? 'no details'} (credits refunded).\n`)
345
+ err.write(`Job ${job.status}: ${job.error?.message ?? 'no details'} (the time it held was given back).\n`)
281
346
  return 1
282
347
  }
283
348
  const directory = resolve(values.out ?? join(dirname(path), `${basename(path, extname(path))} (vocnu ${target})`))
@@ -285,20 +350,19 @@ async function translate(args, { api, err, out, print }) {
285
350
  return 0
286
351
  }
287
352
 
288
- // The grades cheaper than the one asked, dearest first, whose price the balance covers, each with that price: Standard
289
- // and Economy for a voice-over where they have voices of the language, Economy for subtitles alone.
290
- async function cheaperWithin(api, quote, { balance, choice, grade, output, target }) {
291
- 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 }) {
292
356
  const within = []
293
- for (const cheaper of grades.slice(grades.indexOf(grade) + 1)) {
294
- const prices = gradeQuote(quote, cheaper)
357
+ for (const other of GRADES.filter((name) => name !== grade)) {
358
+ const prices = gradeQuote(quote, other)
295
359
  if (!prices) continue
296
- const credits = quotedCredits(prices, ...choice)
297
- if (credits > balance) continue
298
- if (output !== 'subtitles' && (await api.voices(target, cheaper)).length === 0) continue
299
- within.push({ credits, grade: 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])
300
364
  }
301
- return within
365
+ return within.sort((a, b) => b[0] - a[0]).map(([, other]) => other)
302
366
  }
303
367
 
304
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 ADDED
@@ -0,0 +1,214 @@
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'
9
+
10
+ export const SECONDS_PER_CREDIT = { premium: 30, economy: 120 }
11
+
12
+ function positive(value) {
13
+ return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null
14
+ }
15
+
16
+ // The catalog, or none where it cannot be read (an older Vocnu, a hiccup): the time is then the fallback's.
17
+ export async function catalogOf(api) {
18
+ try {
19
+ return await api.catalog()
20
+ } catch {
21
+ return null
22
+ }
23
+ }
24
+
25
+ // How long a credit voices in each grade, by the catalog.
26
+ export function secondsPerCredit(catalog) {
27
+ return Object.fromEntries(GRADES.map((grade) => {
28
+ const known = catalog?.grades?.[grade]
29
+ const rates = known?.rates ?? (grade === 'premium' ? catalog?.rates : undefined)
30
+ const rate = positive(rates?.voiceover_audio)
31
+ return [grade, positive(known?.seconds_per_credit) ?? (rate === null ? SECONDS_PER_CREDIT[grade] : 60 / rate)]
32
+ }))
33
+ }
34
+
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.
53
+ export function offeredGrades(catalog) {
54
+ return GRADES.filter((grade) => grade === 'premium' || catalog?.grades?.[grade])
55
+ }
56
+
57
+ // Whole minutes the credits voice: down for what a balance surely covers, up for what something uses, so neither says
58
+ // more than it gives. Exact to the thousandth first, so half a credit of Standard is a minute, not a hair under one.
59
+ export function minutesOf(credits, seconds, round) {
60
+ const exact = Math.round(((Math.max(0, credits) * seconds) / 60) * 1000) / 1000
61
+ return round === 'up' ? Math.ceil(exact) : Math.floor(exact)
62
+ }
63
+
64
+ // "25 min", "1 h", "2 h 5 min".
65
+ export function duration(minutes) {
66
+ const whole = Math.max(0, Math.round(minutes))
67
+ const hours = Math.floor(whole / 60)
68
+ const rest = whole % 60
69
+ if (hours === 0) return `${rest} min`
70
+ return rest === 0 ? `${hours} h` : `${hours} h ${rest} min`
71
+ }
72
+
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'}`
79
+ }
80
+
81
+ // Whole minutes and the same written, in each grade that has a time for them (`seconds` null leaves a grade out).
82
+ function byGrade(credits, grades, seconds, round) {
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])]))
86
+ return { minutes, time }
87
+ }
88
+
89
+ function day(value) {
90
+ return typeof value === 'string' && !Number.isNaN(Date.parse(value)) ? value : null
91
+ }
92
+
93
+ // The balance as Vocnu's GET credits and catalog say it (`vocnu time --json`, vocnu_credits): the credits as Vocnu
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.
98
+ export function balanceReport(credits, catalog) {
99
+ const times = timesOf(catalog)
100
+ const grades = offeredGrades(catalog)
101
+ const both = (amount) => ({ voice: byGrade(amount, grades, times.voice, 'down'), subtitles: byGrade(amount, grades, times.subtitles, 'down') })
102
+ const balance = typeof credits?.balance === 'number' ? credits.balance : 0
103
+ const left = both(balance)
104
+ const raw = credits?.plan
105
+ const name = typeof raw?.name === 'string' ? raw.name.trim() : ''
106
+ const monthly = positive(raw?.monthly_credits)
107
+ const month = monthly === null ? null : both(monthly)
108
+ const plan = name === '' ? null : {
109
+ id: typeof raw.id === 'string' ? raw.id : null,
110
+ name,
111
+ renews_at: day(raw.renews_at),
112
+ cancel_at_period_end: raw.cancel_at_period_end === true,
113
+ library_unlimited: raw.library_unlimited === true,
114
+ monthly_credits: monthly,
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,
119
+ }
120
+ const expiring = (Array.isArray(credits?.expiring) ? credits.expiring : [])
121
+ .filter((lot) => positive(lot?.credits) !== null && day(lot?.expires_at) !== null)
122
+ .sort((a, b) => Date.parse(a.expires_at) - Date.parse(b.expires_at))
123
+ .map((lot) => {
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
+ }
133
+ })
134
+ return {
135
+ balance,
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]])),
142
+ plan,
143
+ expiring,
144
+ }
145
+ }
146
+
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 })}`)
185
+ const { plan } = report
186
+ if (plan) {
187
+ const parts = [plan.name]
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`)
191
+ if (plan.renews_at) parts.push(`${plan.cancel_at_period_end ? 'ends' : 'renews'} ${plan.renews_at.slice(0, 10)}`)
192
+ if (plan.library_unlimited) parts.push('Library included')
193
+ lines.push(`Plan: ${parts.join(', ')}`)
194
+ }
195
+ for (const lot of report.expiring) {
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)}`)
198
+ }
199
+ return lines
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,6 +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
- // translation, follow it, save the results and share them with a link. Spending credits is a separate tool, so the
3
- // assistant can confirm the price with the user first. stdout carries the protocol only.
2
+ // translation, follow it, save the results and share them with a link. Spending the user's time is a separate tool,
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 (`*_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.
4
7
  import { homedir } from 'node:os'
5
8
  import { join, resolve } from 'node:path'
6
9
 
@@ -11,8 +14,11 @@ import { z } from 'zod'
11
14
  import { VocnuApi } from './api.js'
12
15
  import { loadConfig } from './config.js'
13
16
  import { formatTimeLeft, secondsLeft } from './estimate.js'
17
+ import { currentGrade, gradeFrom, gradeMakes, jobGrade, modeFrom, preferencesOf, preferredGrade } from './grades.js'
18
+ import { balanceLines, balanceReport, catalogOf, gradeBalance, productTime, timesOf } from './hours.js'
14
19
  import {
15
- 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,
16
22
  } from './media.js'
17
23
  import { VERSION } from './version.js'
18
24
 
@@ -35,16 +41,17 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
35
41
 
36
42
  tool('vocnu_languages', {
37
43
  annotations: { readOnlyHint: true },
38
- description: 'Languages Vocnu translates into (code and name); some take subtitles only. voiceover_grades: the '
39
- + 'grades a voice-over into the language can be made in now, "premium" and, where offered, "standard" and '
40
- + '"economy". Subtitles alone come in "premium" or, where offered (price_credits_by_grade of an upload), '
41
- + '"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".',
42
48
  title: 'Vocnu languages',
43
49
  }, async () => {
44
50
  const catalog = await api.catalog()
51
+ // Only the grades on offer, whatever an older Vocnu still lists (backend ADR 0126).
45
52
  return (catalog.languages ?? []).map((l) => ({
46
53
  code: l.code, name: l.name, voiceover: l.voiceover !== false,
47
- ...(l.voiceover_grades ? { voiceover_grades: l.voiceover_grades } : {}),
54
+ ...(l.voiceover_grades ? { voiceover_grades: l.voiceover_grades.filter((grade) => GRADES.includes(grade)) } : {}),
48
55
  }))
49
56
  })
50
57
 
@@ -54,28 +61,53 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
54
61
  + 'sounds, whether it is the default of its type, and a short sample (MP3) the user can listen to. Pass the '
55
62
  + 'chosen id as voice_id to vocnu_start_job, with the same grade: each grade has voices of its own.',
56
63
  inputSchema: {
57
- 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'),
58
67
  language: z.string().describe('Language code, e.g. lt, en, de (see vocnu_languages)'),
59
68
  },
60
69
  title: 'Vocnu voices',
61
- }, async ({ grade, language }) => (await api.voices(language, grade)).map((v) => ({
62
- default: v.default, gender: v.gender, grade: v.grade, id: v.id, name: v.name, sample_url: v.sample_url, traits: v.traits,
63
- })))
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
+ })
64
76
 
65
77
  tool('vocnu_credits', {
66
78
  annotations: { readOnlyHint: true },
67
- description: "The user's Vocnu credit balance. One credit is about one minute of subtitles; a voice-over costs more.",
68
- title: 'Vocnu credits',
69
- }, async () => ({ balance: (await api.credits()).balance }))
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.',
88
+ title: 'Vocnu time left',
89
+ }, async () => {
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 }
95
+ })
70
96
 
71
97
  tool('vocnu_upload_media', {
72
98
  description: 'Upload a local video or audio file (up to 10 GB) to Vocnu, wait until it is analysed and return its '
73
- + 'source_id, length and price in credits for each output: price_credits in Premium, and '
74
- + 'price_credits_by_grade in each grade offered (Standard: a voice-over for half the credits, with simpler '
75
- + 'voices and translation, its subtitles alone Premium\'s at Premium\'s price; Economy: the lowest price, '
76
- + 'a voice-over or subtitles alone at 0.5 credits a minute, a plain synthetic voice reading a quick '
77
- + 'translation), with each grade\'s credits_per_minute (rates may be fractional, every price is whole '
78
- + 'credits). Nothing is charged until vocnu_start_job. '
99
+ + 'source_id, length and the time of the user\'s balance each output uses, as they should hear it: price_time '
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 '
109
+ + 'credits_per_minute) and balance are the same in credits, Vocnu\'s internal unit: tell the user time, never '
110
+ + 'credits. Nothing is used until vocnu_start_job. '
79
111
  + 'captions_only is true for a video nobody speaks in whose story is told in captions burned into the picture: '
80
112
  + 'Vocnu narrates the captions. Large files take minutes to upload.',
81
113
  inputSchema: { path: z.string().describe('Path of the video or audio file on this computer') },
@@ -84,9 +116,10 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
84
116
  const file = where(path)
85
117
  const uploaded = await api.upload(file)
86
118
  const source = await api.waitForSource(uploaded.id)
87
- const { balance } = await api.credits()
119
+ const [{ balance }, catalog] = await Promise.all([api.credits(), catalogOf(api)])
120
+ const times = timesOf(catalog, source.quote)
88
121
  const prices = (quote) => ({
89
- // 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).
90
123
  credits_per_minute: quote.credits_per_minute ?? null,
91
124
  audio: quote.options.voiceover_audio,
92
125
  subtitles: quote.options.subtitles,
@@ -99,15 +132,42 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
99
132
  // What SDH subtitles add to any output (null: not offered).
100
133
  sdh_extra: quote.options.sdh ?? null,
101
134
  })
102
- // A server before the grades prices Premium only.
103
- const offered = Object.keys(source.quote.grades ?? { premium: true })
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)
139
+ return {
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,
143
+ video_by_format: source.has_video
144
+ ? Object.fromEntries(VIDEO_FORMATS.map((format) => [format, told(quotedCredits(quote, 'video', format), true)]))
145
+ : null,
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),
149
+ }
150
+ }
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'
104
158
  return {
105
159
  balance,
160
+ balance_time: typeof balance === 'number'
161
+ ? Object.fromEntries(offered.map((name) => [name, gradeBalance(balance, name, times)]))
162
+ : null,
106
163
  captions_only: source.captions_only === true,
107
164
  duration_seconds: source.duration_seconds,
108
165
  has_video: source.has_video,
109
- price_credits: prices(source.quote),
110
- price_credits_by_grade: Object.fromEntries(offered.map((grade) => [grade, prices(gradeQuote(source.quote, 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)])),
111
171
  source_id: source.id,
112
172
  suggested_video_format: isVideo(file) ? defaultVideoFormat(file) : null,
113
173
  title: source.title,
@@ -115,22 +175,26 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
115
175
  })
116
176
 
117
177
  tool('vocnu_start_job', {
118
- description: 'Start translating an uploaded file (source_id from vocnu_upload_media). Spends the quoted credits '
119
- + '(refunded if the job fails or is cancelled): confirm the price with the user before calling. output "video" '
178
+ description: 'Start translating an uploaded file (source_id from vocnu_upload_media). Uses the quoted time of '
179
+ + 'the user\'s balance (given back if the job fails or is cancelled): confirm the price with the user before '
180
+ + 'calling; balance_after_time is the time left after it, of what the job makes in its grade. output "video" '
120
181
  + 'is the video with the voice-over, "audio" the voice-over audio, "subtitles" subtitles only; every output '
121
182
  + 'also includes subtitles. sdh adds SDH subtitles (sound descriptions, speaker names, songs) for deaf and '
122
183
  + 'hard-of-hearing viewers to any output, at the sdh_extra price. Subtitles may be in the spoken language '
123
184
  + '(target_language = source_language, e.g. German SDH of a German film); a voice-over may not, except for a '
124
- + 'captions_only upload, whose captions the narrator then reads as written. grade "standard" makes the '
125
- + 'voice-over for half the credits, with simpler voices and translation; "economy" makes a voice-over or '
126
- + 'subtitles alone for the lowest price, a plain synthetic voice reading a quick translation; each where '
127
- + 'offered (see price_credits_by_grade and vocnu_languages); the price to confirm is then 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.',
128
191
  inputSchema: {
129
192
  audio_format: z.enum(AUDIO_FORMATS).optional().describe('Voice-over audio format (default m4a)'),
130
193
  burn_subtitles: z.boolean().optional().describe('Burn the subtitles into the picture (video only)'),
131
- grade: z.enum(GRADES).optional().describe('"premium" (default), "standard" or "economy". Standard is for a '
132
- + 'voice-over (its subtitles alone are Premium\'s); Economy makes subtitles alone too, in its own '
133
- + '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)'),
134
198
  original_level: z.number().int().min(0).max(100).optional()
135
199
  .describe('How loud the original sound stays under the voice, in percent: 0 silent, 100 unchanged '
136
200
  + '(default: the level recommended for the upload from how loud its own speech is, else 40). Voice-over '
@@ -156,6 +220,16 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
156
220
  }, async (input) => {
157
221
  const chosen = input.video_formats ?? [input.video_format ?? 'mp4']
158
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
+ }
159
233
  const created = await api.createJob({
160
234
  audio_format: input.audio_format ?? 'm4a',
161
235
  products: productsFor(input.output, input.burn_subtitles, input.sdh === true),
@@ -168,10 +242,17 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
168
242
  ...(input.voice_id ? { voice_id: input.voice_id } : {}),
169
243
  ...(input.original_level === undefined || input.original_off ? {} : { original_level: input.original_level }),
170
244
  ...(input.original_off ? { original_off: true } : {}),
171
- ...(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 }),
172
247
  })
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
173
250
  return {
174
- balance_after: created.credit_balance, grade: created.job.grade, job_id: created.job.id, status: created.job.status,
251
+ balance_after: created.credit_balance,
252
+ balance_after_time: typeof created.credit_balance === 'number'
253
+ ? productTime(created.credit_balance, told, input.output !== 'subtitles', timesOf(catalog), 'down')
254
+ : null,
255
+ grade: created.job.grade, job_id: created.job.id, status: created.job.status,
175
256
  }
176
257
  })
177
258
 
@@ -226,7 +307,7 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
226
307
 
227
308
  tool('vocnu_cancel_job', {
228
309
  annotations: { destructiveHint: true },
229
- description: 'Cancel a queued or running Vocnu job; its credits are refunded.',
310
+ description: 'Cancel a queued or running Vocnu job; the time it held is given back to the user\'s balance.',
230
311
  inputSchema: { job_id: z.string() },
231
312
  title: 'Cancel a Vocnu job',
232
313
  }, async ({ job_id }) => summary(await api.cancel(job_id)))
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