vocnu 0.6.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` | Premium (default), or Standard where Vocnu offers it: a voice-over for half the credits, with simpler voices and translation (subtitles alone are the same in both) |
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
- Standard's with `--grade standard`: 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`.
42
+ another grade's with `--grade standard` or `--grade economy`: 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 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
 
@@ -77,11 +87,12 @@ Claude Desktop (`claude_desktop_config.json`) and other MCP clients:
77
87
 
78
88
  Then ask, for example, “Dub ~/Videos/film.mkv into Lithuanian with Vocnu”. The assistant uploads the file
79
89
  (`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), checks on it
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.6.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,9 +8,10 @@ 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
- VIDEO_FORMATS, videoFormatsFrom,
14
+ SUBTITLE_GRADES, VIDEO_FORMATS, videoFormatsFrom,
14
15
  } from './media.js'
15
16
  import { VERSION } from './version.js'
16
17
 
@@ -21,14 +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
- --grade premium|standard Standard's voices instead of Premium's
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 Premium (default), or Standard: a voice-over for half the credits,
31
- with simpler voices and translation
31
+ --grade premium|standard|economy Premium (default); Standard: simpler voices and translation, and your
32
+ time lasts twice as long; or Economy, where it lasts longest: a plain
33
+ synthetic voice reading a quick translation, for a voice-over or subtitles
34
+ alone (Standard and Economy where Vocnu offers them)
32
35
  --from <lang> Spoken language (default: detected)
33
36
  --voice male|female|<voice id> A voice type, or a voice from \`vocnu voices\` (default: male)
34
37
  --format mp4|mkv|mov|webm|avi Video file format, or several: mp4,mkv (default: the upload's, else mp4)
@@ -47,7 +50,7 @@ Usage:
47
50
  vocnu status <job> Progress, time left and files of a job
48
51
  vocnu download <job> [--out <dir>] Save the files of a finished job
49
52
  vocnu share <job> [--revoke] A link anyone can open to play and download the files
50
- vocnu cancel <job> Cancel a job (its credits are refunded)
53
+ vocnu cancel <job> Cancel a job (the time it held is given back)
51
54
  vocnu mcp Run the Vocnu MCP server (for Claude and other assistants)
52
55
 
53
56
  The token can also come from VOCNU_TOKEN.`
@@ -78,11 +81,10 @@ export async function main(argv, { env = process.env, out = process.stdout, err
78
81
  await forgetCredentials(env)
79
82
  print('Signed out: the saved token is gone (revoke it in the app if it may have leaked).')
80
83
  return 0
81
- case 'credits': {
82
- const { balance } = await api.credits()
83
- print(`${balance} credits`)
84
- return 0
85
- }
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 })
86
88
  case 'languages':
87
89
  return await languages(api, print)
88
90
  case 'voices':
@@ -99,7 +101,7 @@ export async function main(argv, { env = process.env, out = process.stdout, err
99
101
  return await share(rest, { api, print })
100
102
  case 'cancel': {
101
103
  const job = await api.cancel(required(rest[0], 'job id'))
102
- print(`Cancelled ${job.id}; its credits were refunded.`)
104
+ print(`Cancelled ${job.id}; the time it held was given back.`)
103
105
  return 0
104
106
  }
105
107
  default:
@@ -120,7 +122,12 @@ function required(value, what) {
120
122
  }
121
123
 
122
124
  function checkGrade(grade) {
123
- if (grade !== undefined && !GRADES.includes(grade)) throw new UsageError(`--grade is ${GRADES.join(' or ')}.`)
125
+ if (grade !== undefined && !GRADES.includes(grade)) throw new UsageError(`--grade is ${listed(GRADES)}.`)
126
+ }
127
+
128
+ // premium, standard or economy
129
+ function listed(names) {
130
+ return names.length > 1 ? `${names.slice(0, -1).join(', ')} or ${names.at(-1)}` : names.join('')
124
131
  }
125
132
 
126
133
  function parse(args, options) {
@@ -138,8 +145,19 @@ async function login(args, { api, config, env, print }) {
138
145
  const url = (values.url ?? config.url ?? DEFAULT_URL).replace(/\/+$/, '')
139
146
  const checked = new VocnuApi({ fetch: api.fetch, token, url })
140
147
  const { balance } = await checked.credits()
148
+ const left = gradeTime(balance, 'premium', secondsPerCredit(await catalogOf(checked)), 'down')
141
149
  const path = await saveCredentials({ token, url }, env)
142
- 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)
143
161
  return 0
144
162
  }
145
163
 
@@ -196,8 +214,10 @@ async function translate(args, { api, err, out, print }) {
196
214
  // Premium unless asked (backend ADR 0080); a job that names none is Premium's on every server.
197
215
  const grade = values.grade ?? 'premium'
198
216
  checkGrade(values.grade)
199
- if (grade !== 'premium' && output === 'subtitles') {
200
- throw new UsageError('--grade is for a voice-over; subtitles alone are the same in both grades.')
217
+ // Subtitles alone come in Premium or in Economy's own translation; Standard's would be Premium's.
218
+ if (output === 'subtitles' && !SUBTITLE_GRADES.includes(grade)) {
219
+ const names = listed(SUBTITLE_GRADES.map((name) => GRADE_NAMES[name]))
220
+ throw new UsageError(`--grade ${grade} is for a voice-over: subtitles alone come in ${names}.`)
201
221
  }
202
222
  if (!OUTPUTS.includes(output)) throw new UsageError(`--output is one of ${OUTPUTS.join(', ')}.`)
203
223
  if (!videoFormats) throw new UsageError(`--format is one or more of ${VIDEO_FORMATS.join(', ')}, separated by commas.`)
@@ -228,14 +248,20 @@ async function translate(args, { api, err, out, print }) {
228
248
  if (!prices) throw new VocnuError(`${GRADE_NAMES[grade]} is not available yet: use --grade premium. Nothing was charged.`)
229
249
  const choice = [output, videoFormats, values['burn-subtitles'], values.sdh]
230
250
  const credits = quotedCredits(prices, ...choice)
231
- const { balance } = await api.credits()
232
- // The grade is named once the server prices grades; a server before them makes only Premium.
233
- const graded = source.quote.grades ? `, ${GRADE_NAMES[grade]}` : ''
234
- print(`Price: ${credits} credits (${source.quote.minutes} min${graded}). Balance: ${balance} credits.`)
235
- // A voice-over the balance covers in Standard but not in Premium says so.
236
- if (output !== 'subtitles' && grade === 'premium' && credits > balance) {
237
- const cheaper = await standardWithin(api, source.quote, target, balance, choice)
238
- if (cheaper !== null) print(`Not enough credits for Premium: in Standard it costs ${cheaper} (add --grade standard).`)
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.
259
+ if (credits > balance) {
260
+ const cheaper = await cheaperWithin(api, source.quote, { balance, choice, grade, output, target })
261
+ if (cheaper.length > 0) {
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 ')}.`)
264
+ }
239
265
  }
240
266
  if (!values.yes) {
241
267
  if (!process.stdin.isTTY) throw new UsageError('Add --yes to start without confirming the price.')
@@ -259,12 +285,12 @@ async function translate(args, { api, err, out, print }) {
259
285
  ...(originalOff ? { original_off: true } : {}),
260
286
  ...(values.grade === undefined ? {} : { grade }),
261
287
  })
262
- 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).`)
263
289
  if (values['no-wait']) return 0
264
290
 
265
291
  const job = await follow(api, created.job.id, progress)
266
292
  if (job.status !== 'completed') {
267
- 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`)
268
294
  return 1
269
295
  }
270
296
  const directory = resolve(values.out ?? join(dirname(path), `${basename(path, extname(path))} (vocnu ${target})`))
@@ -272,14 +298,20 @@ async function translate(args, { api, err, out, print }) {
272
298
  return 0
273
299
  }
274
300
 
275
- // What a voice-over short of credits in Premium costs in Standard, when the balance covers it there and Standard has
276
- // voices of the language; else null.
277
- async function standardWithin(api, quote, target, balance, choice) {
278
- const standard = gradeQuote(quote, 'standard')
279
- if (!standard) return null
280
- const credits = quotedCredits(standard, ...choice)
281
- if (credits > balance || (await api.voices(target, 'standard')).length === 0) return null
282
- return credits
301
+ // The grades cheaper than the one asked, dearest first, whose price the balance covers: Standard and Economy for a
302
+ // voice-over where they have voices of the language, Economy for subtitles alone.
303
+ async function cheaperWithin(api, quote, { balance, choice, grade, output, target }) {
304
+ const grades = output === 'subtitles' ? SUBTITLE_GRADES : GRADES
305
+ const within = []
306
+ for (const cheaper of grades.slice(grades.indexOf(grade) + 1)) {
307
+ const prices = gradeQuote(quote, cheaper)
308
+ if (!prices) continue
309
+ const credits = quotedCredits(prices, ...choice)
310
+ if (credits > balance) continue
311
+ if (output !== 'subtitles' && (await api.voices(target, cheaper)).length === 0) continue
312
+ within.push(cheaper)
313
+ }
314
+ return within
283
315
  }
284
316
 
285
317
  async function follow(api, id, progress) {
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'
@@ -36,7 +39,9 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
36
39
  tool('vocnu_languages', {
37
40
  annotations: { readOnlyHint: true },
38
41
  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".',
42
+ + 'grades a voice-over into the language can be made in now, "premium" and, where offered, "standard" and '
43
+ + '"economy". Subtitles alone come in "premium" or, where offered (price_time_by_grade of an upload), '
44
+ + '"economy", into any language.',
40
45
  title: 'Vocnu languages',
41
46
  }, async () => {
42
47
  const catalog = await api.catalog()
@@ -52,7 +57,7 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
52
57
  + 'sounds, whether it is the default of its type, and a short sample (MP3) the user can listen to. Pass the '
53
58
  + 'chosen id as voice_id to vocnu_start_job, with the same grade: each grade has voices of its own.',
54
59
  inputSchema: {
55
- grade: z.enum(GRADES).optional().describe('Whose voices: "premium" (default) or "standard"'),
60
+ grade: z.enum(GRADES).optional().describe('Whose voices: "premium" (default), "standard" or "economy"'),
56
61
  language: z.string().describe('Language code, e.g. lt, en, de (see vocnu_languages)'),
57
62
  },
58
63
  title: 'Vocnu voices',
@@ -62,15 +67,30 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
62
67
 
63
68
  tool('vocnu_credits', {
64
69
  annotations: { readOnlyHint: true },
65
- description: "The user's Vocnu credit balance. One credit is about one minute of subtitles; a voice-over costs more.",
66
- title: 'Vocnu credits',
67
- }, 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
+ })
68
82
 
69
83
  tool('vocnu_upload_media', {
70
84
  description: 'Upload a local video or audio file (up to 10 GB) to Vocnu, wait until it is analysed and return its '
71
- + 'source_id, length and price in credits for each output: price_credits in Premium, and '
72
- + 'price_credits_by_grade in each grade offered (Standard: a voice-over for half the credits, with simpler '
73
- + 'voices and translation; subtitles alone cost the same). 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. '
74
94
  + 'captions_only is true for a video nobody speaks in whose story is told in captions burned into the picture: '
75
95
  + 'Vocnu narrates the captions. Large files take minutes to upload.',
76
96
  inputSchema: { path: z.string().describe('Path of the video or audio file on this computer') },
@@ -79,8 +99,11 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
79
99
  const file = where(path)
80
100
  const uploaded = await api.upload(file)
81
101
  const source = await api.waitForSource(uploaded.id)
82
- const { balance } = await api.credits()
102
+ const [{ balance }, catalog] = await Promise.all([api.credits(), catalogOf(api)])
103
+ const seconds = secondsPerCredit(catalog)
83
104
  const prices = (quote) => ({
105
+ // The grade's rates a minute, such as 0.5 in Economy (null from a server before them).
106
+ credits_per_minute: quote.credits_per_minute ?? null,
84
107
  audio: quote.options.voiceover_audio,
85
108
  subtitles: quote.options.subtitles,
86
109
  video: source.has_video ? quotedCredits(quote, 'video', defaultVideoFormat(file)) : null,
@@ -92,15 +115,40 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
92
115
  // What SDH subtitles add to any output (null: not offered).
93
116
  sdh_extra: quote.options.sdh ?? null,
94
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
+ }
95
135
  // A server before the grades prices Premium only.
96
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))
97
140
  return {
98
141
  balance,
142
+ balance_time: typeof balance === 'number'
143
+ ? Object.fromEntries(told.map((grade) => [grade, duration(minutesOf(balance, seconds[grade], 'down'))]))
144
+ : null,
99
145
  captions_only: source.captions_only === true,
100
146
  duration_seconds: source.duration_seconds,
101
147
  has_video: source.has_video,
102
148
  price_credits: prices(source.quote),
103
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)])),
104
152
  source_id: source.id,
105
153
  suggested_video_format: isVideo(file) ? defaultVideoFormat(file) : null,
106
154
  title: source.title,
@@ -108,20 +156,24 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
108
156
  })
109
157
 
110
158
  tool('vocnu_start_job', {
111
- description: 'Start translating an uploaded file (source_id from vocnu_upload_media). Spends the quoted credits '
112
- + '(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" '
113
162
  + 'is the video with the voice-over, "audio" the voice-over audio, "subtitles" subtitles only; every output '
114
163
  + 'also includes subtitles. sdh adds SDH subtitles (sound descriptions, speaker names, songs) for deaf and '
115
164
  + 'hard-of-hearing viewers to any output, at the sdh_extra price. Subtitles may be in the spoken language '
116
165
  + '(target_language = source_language, e.g. German SDH of a German film); a voice-over may not, except for a '
117
166
  + 'captions_only upload, whose captions the narrator then reads as written. grade "standard" makes the '
118
- + 'voice-over for half the credits, with simpler voices and translation, where offered (see '
119
- + '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.',
120
171
  inputSchema: {
121
172
  audio_format: z.enum(AUDIO_FORMATS).optional().describe('Voice-over audio format (default m4a)'),
122
173
  burn_subtitles: z.boolean().optional().describe('Burn the subtitles into the picture (video only)'),
123
- grade: z.enum(GRADES).optional().describe('"premium" (default) or "standard". Voice-over only: subtitles alone '
124
- + 'are the same in both. A voice_id must be one of the grade\'s voices (vocnu_voices with the grade)'),
174
+ grade: z.enum(GRADES).optional().describe('"premium" (default), "standard" or "economy". Standard is for a '
175
+ + 'voice-over (its subtitles alone are Premium\'s); Economy makes subtitles alone too, in its own '
176
+ + 'translation. A voice_id must be one of the grade\'s voices (vocnu_voices with the grade)'),
125
177
  original_level: z.number().int().min(0).max(100).optional()
126
178
  .describe('How loud the original sound stays under the voice, in percent: 0 silent, 100 unchanged '
127
179
  + '(default: the level recommended for the upload from how loud its own speech is, else 40). Voice-over '
@@ -161,8 +213,15 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
161
213
  ...(input.original_off ? { original_off: true } : {}),
162
214
  ...(input.grade ? { grade: input.grade } : {}),
163
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))
164
219
  return {
165
- 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,
166
225
  }
167
226
  })
168
227
 
@@ -217,7 +276,7 @@ export function createServer(api, { cwd = process.cwd() } = {}) {
217
276
 
218
277
  tool('vocnu_cancel_job', {
219
278
  annotations: { destructiveHint: true },
220
- 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.',
221
280
  inputSchema: { job_id: z.string() },
222
281
  title: 'Cancel a Vocnu job',
223
282
  }, async ({ job_id }) => summary(await api.cancel(job_id)))
package/src/media.js CHANGED
@@ -10,10 +10,12 @@ 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 of voice-over (backend ADR 0080): Premium, the default, and Standard, a voice-over for half the
14
- // credits. Subtitles alone are the same in both.
15
- export const GRADES = ['premium', 'standard']
16
- export const GRADE_NAMES = { premium: 'Premium', standard: 'Standard' }
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' }
17
19
 
18
20
  export function contentType(path) {
19
21
  return TYPES[extname(path).toLowerCase()] ?? null