vocnu 0.7.0 → 0.8.0

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,39 @@ 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
27
  | `--output video\|audio\|subtitles` | the video with the voice-over (default for video files), the voice-over audio, or subtitles only |
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 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 |
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
41
  `vocnu voices <lang>` lists the voices of a language with a link to a short sample of each, Premium's, or
42
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`.
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 in each grade, your plan and what expires
49
+ npx vocnu time --json # the same for scripts
50
+ ```
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.
45
55
 
46
56
  ## Share the results
47
57
 
@@ -80,8 +90,9 @@ Then ask, for example, “Dub ~/Videos/film.mkv into Lithuanian with Vocnu”. T
80
90
  Premium unless you ask for Standard or Economy), checks on it
81
91
  (`vocnu_job_status`) and saves the files (`vocnu_download_results`) or gives you a link to send
82
92
  (`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`.
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.
85
96
 
86
97
  ## Development
87
98
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "vocnu",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
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/cli.js CHANGED
@@ -8,6 +8,7 @@ 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
12
  import {
12
13
  AUDIO_FORMATS, contentType, defaultVideoFormat, GRADE_NAMES, GRADES, gradeQuote, isVideo, OUTPUTS, productsFor, quotedCredits,
13
14
  SUBTITLE_GRADES, VIDEO_FORMATS, videoFormatsFrom,
@@ -21,16 +22,16 @@ const HELP = `Vocnu ${VERSION}: AI voice-over and subtitles for your videos (htt
21
22
  Usage:
22
23
  vocnu login [--token <token>] Save an API token (app.vocnu.com → Settings → API & MCP)
23
24
  vocnu logout Forget the saved token
24
- vocnu credits Your credit balance
25
+ vocnu time [--json] Your time left in each grade, your plan and what expires
25
26
  vocnu languages Languages you can translate into
26
27
  vocnu voices <lang> Voices of a language, each with a short sample to listen to
27
28
  --grade premium|standard|economy Another grade's voices instead of Premium's
28
29
  vocnu translate <file> --to <lang> Upload, see the price, translate and download the results
29
30
  --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)
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)
34
35
  --from <lang> Spoken language (default: detected)
35
36
  --voice male|female|<voice id> A voice type, or a voice from \`vocnu voices\` (default: male)
36
37
  --format mp4|mkv|mov|webm|avi Video file format, or several: mp4,mkv (default: the upload's, else mp4)
@@ -49,7 +50,7 @@ Usage:
49
50
  vocnu status <job> Progress, time left and files of a job
50
51
  vocnu download <job> [--out <dir>] Save the files of a finished job
51
52
  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)
53
+ vocnu cancel <job> Cancel a job (the time it held is given back)
53
54
  vocnu mcp Run the Vocnu MCP server (for Claude and other assistants)
54
55
 
55
56
  The token can also come from VOCNU_TOKEN.`
@@ -80,11 +81,10 @@ export async function main(argv, { env = process.env, out = process.stdout, err
80
81
  await forgetCredentials(env)
81
82
  print('Signed out: the saved token is gone (revoke it in the app if it may have leaked).')
82
83
  return 0
83
- case 'credits': {
84
- const { balance } = await api.credits()
85
- print(`${balance} credits`)
86
- return 0
87
- }
84
+ // `credits`, its name before Vocnu told time (backend ADR 0122), stays for scripts that call it.
85
+ case 'time':
86
+ case 'credits':
87
+ return await timeLeft(rest, { api, print })
88
88
  case 'languages':
89
89
  return await languages(api, print)
90
90
  case 'voices':
@@ -101,7 +101,7 @@ export async function main(argv, { env = process.env, out = process.stdout, err
101
101
  return await share(rest, { api, print })
102
102
  case 'cancel': {
103
103
  const job = await api.cancel(required(rest[0], 'job id'))
104
- print(`Cancelled ${job.id}; its credits were refunded.`)
104
+ print(`Cancelled ${job.id}; the time it held was given back.`)
105
105
  return 0
106
106
  }
107
107
  default:
@@ -145,8 +145,19 @@ async function login(args, { api, config, env, print }) {
145
145
  const url = (values.url ?? config.url ?? DEFAULT_URL).replace(/\/+$/, '')
146
146
  const checked = new VocnuApi({ fetch: api.fetch, token, url })
147
147
  const { balance } = await checked.credits()
148
+ const left = gradeTime(balance, 'premium', secondsPerCredit(await catalogOf(checked)), 'down')
148
149
  const path = await saveCredentials({ token, url }, env)
149
- print(`Signed in (${balance} credits). Token saved in ${path}.`)
150
+ print(`Signed in (${left} left). Token saved in ${path}.`)
151
+ return 0
152
+ }
153
+
154
+ // The time the balance voices in each grade, the plan and what expires; `--json` adds the credits Vocnu counts in.
155
+ async function timeLeft(args, { api, print }) {
156
+ const { values } = parse(args, { json: { type: 'boolean' } })
157
+ const [answer, catalog] = await Promise.all([api.credits(), catalogOf(api)])
158
+ 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)
150
161
  return 0
151
162
  }
152
163
 
@@ -237,17 +248,19 @@ async function translate(args, { api, err, out, print }) {
237
248
  if (!prices) throw new VocnuError(`${GRADE_NAMES[grade]} is not available yet: use --grade premium. Nothing was charged.`)
238
249
  const choice = [output, videoFormats, values['burn-subtitles'], values.sdh]
239
250
  const credits = quotedCredits(prices, ...choice)
240
- 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.
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')
255
+ 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.`)
258
+ // Short of time in the grade asked, the cheaper grades the balance covers say so.
245
259
  if (credits > balance) {
246
260
  const cheaper = await cheaperWithin(api, source.quote, { balance, choice, grade, output, target })
247
261
  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(', ')}.`)
262
+ const offers = cheaper.map((name) => `${GRADE_NAMES[name]} (add --grade ${name})`)
263
+ print(`Not enough time left for ${GRADE_NAMES[grade]}: it fits in ${offers.join(' or ')}.`)
251
264
  }
252
265
  }
253
266
  if (!values.yes) {
@@ -272,12 +285,12 @@ async function translate(args, { api, err, out, print }) {
272
285
  ...(originalOff ? { original_off: true } : {}),
273
286
  ...(values.grade === undefined ? {} : { grade }),
274
287
  })
275
- print(`Started job ${created.job.id} (${created.credit_balance} credits left).`)
288
+ print(`Started job ${created.job.id} (${gradeTime(created.credit_balance, told, seconds, 'down')} left).`)
276
289
  if (values['no-wait']) return 0
277
290
 
278
291
  const job = await follow(api, created.job.id, progress)
279
292
  if (job.status !== 'completed') {
280
- err.write(`Job ${job.status}: ${job.error?.message ?? 'no details'} (credits refunded).\n`)
293
+ err.write(`Job ${job.status}: ${job.error?.message ?? 'no details'} (the time it held was given back).\n`)
281
294
  return 1
282
295
  }
283
296
  const directory = resolve(values.out ?? join(dirname(path), `${basename(path, extname(path))} (vocnu ${target})`))
@@ -285,8 +298,8 @@ async function translate(args, { api, err, out, print }) {
285
298
  return 0
286
299
  }
287
300
 
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.
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.
290
303
  async function cheaperWithin(api, quote, { balance, choice, grade, output, target }) {
291
304
  const grades = output === 'subtitles' ? SUBTITLE_GRADES : GRADES
292
305
  const within = []
@@ -296,7 +309,7 @@ async function cheaperWithin(api, quote, { balance, choice, grade, output, targe
296
309
  const credits = quotedCredits(prices, ...choice)
297
310
  if (credits > balance) continue
298
311
  if (output !== 'subtitles' && (await api.voices(target, cheaper)).length === 0) continue
299
- within.push({ credits, grade: cheaper })
312
+ within.push(cheaper)
300
313
  }
301
314
  return within
302
315
  }
package/src/hours.js ADDED
@@ -0,0 +1,136 @@
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'
7
+
8
+ export const SECONDS_PER_CREDIT = { premium: 30, standard: 60, economy: 120 }
9
+
10
+ function positive(value) {
11
+ return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null
12
+ }
13
+
14
+ // The catalog, or none where it cannot be read (an older Vocnu, a hiccup): the time is then the fallback's.
15
+ export async function catalogOf(api) {
16
+ try {
17
+ return await api.catalog()
18
+ } catch {
19
+ return null
20
+ }
21
+ }
22
+
23
+ // How long a credit voices in each grade, by the catalog.
24
+ export function secondsPerCredit(catalog) {
25
+ return Object.fromEntries(GRADES.map((grade) => {
26
+ const known = catalog?.grades?.[grade]
27
+ const rates = known?.rates ?? (grade === 'premium' ? catalog?.rates : undefined)
28
+ const rate = positive(rates?.voiceover_audio)
29
+ return [grade, positive(known?.seconds_per_credit) ?? (rate === null ? SECONDS_PER_CREDIT[grade] : 60 / rate)]
30
+ }))
31
+ }
32
+
33
+ // The grades on offer, Premium first: Premium alone where the catalog names no other.
34
+ export function offeredGrades(catalog) {
35
+ return GRADES.filter((grade) => grade === 'premium' || catalog?.grades?.[grade])
36
+ }
37
+
38
+ // 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.
40
+ export function minutesOf(credits, seconds, round) {
41
+ const exact = Math.round(((Math.max(0, credits) * seconds) / 60) * 1000) / 1000
42
+ return round === 'up' ? Math.ceil(exact) : Math.floor(exact)
43
+ }
44
+
45
+ // "25 min", "1 h", "2 h 5 min".
46
+ export function duration(minutes) {
47
+ const whole = Math.max(0, Math.round(minutes))
48
+ const hours = Math.floor(whole / 60)
49
+ const rest = whole % 60
50
+ if (hours === 0) return `${rest} min`
51
+ return rest === 0 ? `${hours} h` : `${hours} h ${rest} min`
52
+ }
53
+
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'
64
+ }
65
+
66
+ 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])]))
69
+ return { minutes, time }
70
+ }
71
+
72
+ function day(value) {
73
+ return typeof value === 'string' && !Number.isNaN(Date.parse(value)) ? value : null
74
+ }
75
+
76
+ // 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.
80
+ export function balanceReport(credits, catalog) {
81
+ const seconds = secondsPerCredit(catalog)
82
+ const grades = offeredGrades(catalog)
83
+ const balance = typeof credits?.balance === 'number' ? credits.balance : 0
84
+ const left = byGrade(balance, grades, seconds, 'down')
85
+ const raw = credits?.plan
86
+ const name = typeof raw?.name === 'string' ? raw.name.trim() : ''
87
+ const monthly = positive(raw?.monthly_credits)
88
+ const month = monthly === null ? null : byGrade(monthly, grades, seconds, 'down')
89
+ const plan = name === '' ? null : {
90
+ id: typeof raw.id === 'string' ? raw.id : null,
91
+ name,
92
+ renews_at: day(raw.renews_at),
93
+ cancel_at_period_end: raw.cancel_at_period_end === true,
94
+ library_unlimited: raw.library_unlimited === true,
95
+ monthly_credits: monthly,
96
+ monthly_minutes: month?.minutes ?? null,
97
+ monthly_time: month?.time ?? null,
98
+ }
99
+ const expiring = (Array.isArray(credits?.expiring) ? credits.expiring : [])
100
+ .filter((lot) => positive(lot?.credits) !== null && day(lot?.expires_at) !== null)
101
+ .sort((a, b) => Date.parse(a.expires_at) - Date.parse(b.expires_at))
102
+ .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 }
105
+ })
106
+ return {
107
+ balance,
108
+ balance_minutes: left.minutes,
109
+ balance_time: left.time,
110
+ seconds_per_credit: Object.fromEntries(grades.map((grade) => [grade, seconds[grade]])),
111
+ plan,
112
+ expiring,
113
+ }
114
+ }
115
+
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}`]
122
+ const { plan } = report
123
+ if (plan) {
124
+ 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`)
127
+ if (plan.renews_at) parts.push(`${plan.cancel_at_period_end ? 'ends' : 'renews'} ${plan.renews_at.slice(0, 10)}`)
128
+ if (plan.library_unlimited) parts.push('Library included')
129
+ lines.push(`Plan: ${parts.join(', ')}`)
130
+ }
131
+ 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)}`)
134
+ }
135
+ return lines
136
+ }
package/src/mcp.js CHANGED
@@ -1,6 +1,8 @@
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 of a grade (`*_time`) beside the credits Vocnu counts in. stdout carries the
5
+ // protocol only.
4
6
  import { homedir } from 'node:os'
5
7
  import { join, resolve } from 'node:path'
6
8
 
@@ -11,6 +13,7 @@ import { z } from 'zod'
11
13
  import { VocnuApi } from './api.js'
12
14
  import { loadConfig } from './config.js'
13
15
  import { formatTimeLeft, secondsLeft } from './estimate.js'
16
+ import { balanceReport, catalogOf, costGrade, duration, gradeTime, minutesOf, secondsPerCredit } from './hours.js'
14
17
  import {
15
18
  AUDIO_FORMATS, defaultVideoFormat, GRADES, gradeQuote, isVideo, OUTPUTS, productsFor, quotedCredits, VIDEO_FORMATS,
16
19
  } from './media.js'
@@ -37,7 +40,7 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
37
40
  annotations: { readOnlyHint: true },
38
41
  description: 'Languages Vocnu translates into (code and name); some take subtitles only. voiceover_grades: the '
39
42
  + '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), '
43
+ + '"economy". Subtitles alone come in "premium" or, where offered (price_time_by_grade of an upload), '
41
44
  + '"economy", into any language.',
42
45
  title: 'Vocnu languages',
43
46
  }, async () => {
@@ -64,18 +67,30 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
64
67
 
65
68
  tool('vocnu_credits', {
66
69
  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 }))
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.',
77
+ title: 'Vocnu time left',
78
+ }, async () => {
79
+ const [credits, catalog] = await Promise.all([api.credits(), catalogOf(api)])
80
+ return balanceReport(credits, catalog)
81
+ })
70
82
 
71
83
  tool('vocnu_upload_media', {
72
84
  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. '
85
+ + '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 '
92
+ + 'credits_per_minute) and balance are the same in credits, Vocnu\'s internal unit: tell the user time, never '
93
+ + 'credits. Nothing is used until vocnu_start_job. '
79
94
  + 'captions_only is true for a video nobody speaks in whose story is told in captions burned into the picture: '
80
95
  + 'Vocnu narrates the captions. Large files take minutes to upload.',
81
96
  inputSchema: { path: z.string().describe('Path of the video or audio file on this computer') },
@@ -84,7 +99,8 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
84
99
  const file = where(path)
85
100
  const uploaded = await api.upload(file)
86
101
  const source = await api.waitForSource(uploaded.id)
87
- const { balance } = await api.credits()
102
+ const [{ balance }, catalog] = await Promise.all([api.credits(), catalogOf(api)])
103
+ const seconds = secondsPerCredit(catalog)
88
104
  const prices = (quote) => ({
89
105
  // The grade's rates a minute, such as 0.5 in Economy (null from a server before them).
90
106
  credits_per_minute: quote.credits_per_minute ?? null,
@@ -99,15 +115,40 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
99
115
  // What SDH subtitles add to any output (null: not offered).
100
116
  sdh_extra: quote.options.sdh ?? null,
101
117
  })
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)
123
+ 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,
127
+ video_by_format: source.has_video
128
+ ? Object.fromEntries(VIDEO_FORMATS.map((format) => [format, voiced(quotedCredits(quote, 'video', format))]))
129
+ : 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),
133
+ }
134
+ }
102
135
  // A server before the grades prices Premium only.
103
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))
104
140
  return {
105
141
  balance,
142
+ balance_time: typeof balance === 'number'
143
+ ? Object.fromEntries(told.map((grade) => [grade, duration(minutesOf(balance, seconds[grade], 'down'))]))
144
+ : null,
106
145
  captions_only: source.captions_only === true,
107
146
  duration_seconds: source.duration_seconds,
108
147
  has_video: source.has_video,
109
148
  price_credits: prices(source.quote),
110
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)])),
111
152
  source_id: source.id,
112
153
  suggested_video_format: isVideo(file) ? defaultVideoFormat(file) : null,
113
154
  title: source.title,
@@ -115,16 +156,18 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
115
156
  })
116
157
 
117
158
  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" '
159
+ description: 'Start translating an uploaded file (source_id from vocnu_upload_media). Uses the quoted time of '
160
+ + '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" '
120
162
  + 'is the video with the voice-over, "audio" the voice-over audio, "subtitles" subtitles only; every output '
121
163
  + 'also includes subtitles. sdh adds SDH subtitles (sound descriptions, speaker names, songs) for deaf and '
122
164
  + 'hard-of-hearing viewers to any output, at the sdh_extra price. Subtitles may be in the spoken language '
123
165
  + '(target_language = source_language, e.g. German SDH of a German film); a voice-over may not, except for a '
124
166
  + '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.',
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.',
128
171
  inputSchema: {
129
172
  audio_format: z.enum(AUDIO_FORMATS).optional().describe('Voice-over audio format (default m4a)'),
130
173
  burn_subtitles: z.boolean().optional().describe('Burn the subtitles into the picture (video only)'),
@@ -170,8 +213,15 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
170
213
  ...(input.original_off ? { original_off: true } : {}),
171
214
  ...(input.grade ? { grade: input.grade } : {}),
172
215
  })
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))
173
219
  return {
174
- balance_after: created.credit_balance, grade: created.job.grade, job_id: created.job.id, status: created.job.status,
220
+ balance_after: created.credit_balance,
221
+ balance_after_time: typeof created.credit_balance === 'number'
222
+ ? gradeTime(created.credit_balance, told, seconds, 'down')
223
+ : null,
224
+ grade: created.job.grade, job_id: created.job.id, status: created.job.status,
175
225
  }
176
226
  })
177
227
 
@@ -226,7 +276,7 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
226
276
 
227
277
  tool('vocnu_cancel_job', {
228
278
  annotations: { destructiveHint: true },
229
- description: 'Cancel a queued or running Vocnu job; its credits are refunded.',
279
+ description: 'Cancel a queued or running Vocnu job; the time it held is given back to the user\'s balance.',
230
280
  inputSchema: { job_id: z.string() },
231
281
  title: 'Cancel a Vocnu job',
232
282
  }, async ({ job_id }) => summary(await api.cancel(job_id)))