Talon/aidio-description
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Modernize codebase

Browse Source
This commit is contained in:
Talon
2026-05-13 02:17:07 +02:00
parent 507d4f6474
commit fc02d2001c
13 changed files with 6190 additions and 954 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
index.js
View File

@@ -21,7 +21,7 @@ const defaultConfig = {
// Vision AI settings
visionProvider: "gemini",
visionModel: "gemini-2.0-flash",
visionModel: "gemini-3.0-flash",
visionProviders: {
openai: {
apiKey: process.env.OPENAI_API_KEY,

6552
package-lock.json generated
View File

File diff suppressed because it is too large Load Diff

10
package.json
View File

@@ -4,10 +4,16 @@
"description": "Generate AI-powered audio descriptions for video content",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"bin": {
"aidio-desc": "./dist/cli/index.js"
},
"files": [
"dist"
],
"scripts": {
"build": "tsc",
"start": "node dist/index.js",
"dev": "ts-node src/index.ts",
"start": "node dist/cli/index.js",
"dev": "ts-node src/cli/index.ts",
"test": "jest",
"lint": "eslint src/**/*.ts",
"prepublishOnly": "npm run build"

35
src/cli/args.ts
View File

@@ -1,11 +1,36 @@
import yargs from 'yargs/yargs';
import { hideBin } from 'yargs/helpers';
export interface CLIArgs {
_: (string | number)[];
$0: string;
video_file_path?: string;
captureIntervalSeconds?: number;
contextWindowSize?: number;
visionProvider?: string;
visionModel?: string;
ttsProvider?: string;
ttsModel?: string;
ttsVoice?: string;
ttsSpeedFactor?: number;
outputDir?: string;
tempDir?: string;
batchTimeMode?: boolean;
batchWindowDuration?: number;
framesInBatch?: number;
defaultPrompt?: string;
changePrompt?: string;
batchPrompt?: string;
estimate?: boolean;
config?: string;
saveConfig?: string;
}
/**
* Parse command line arguments
*/
export function parseCommandLineArgs() {
return yargs(hideBin(process.argv))
export function parseCommandLineArgs(): CLIArgs {
const parsed = yargs(hideBin(process.argv))
.usage('Usage: $0 <video_file_path> [options]')
.positional('video_file_path', {
describe: 'Path to the input video file',
@@ -21,7 +46,6 @@ export function parseCommandLineArgs() {
describe: 'Number of frames to keep in context',
type: 'number'
})
// Vision provider options
.option('visionProvider', {
describe: 'Provider to use for vision AI',
type: 'string'
@@ -30,7 +54,6 @@ export function parseCommandLineArgs() {
describe: 'Model to use for vision AI',
type: 'string'
})
// TTS provider options
.option('ttsProvider', {
describe: 'Provider to use for text-to-speech',
type: 'string'
@@ -107,5 +130,7 @@ export function parseCommandLineArgs() {
.example('$0 video.mp4 --estimate', 'Only estimate the processing cost')
.example('$0 video.mp4 --config myconfig.json', 'Use settings from a config file')
.example('$0 video.mp4 --saveConfig myconfig.json', 'Save current settings to a config file')
.argv;
.argv as unknown as CLIArgs;
return parsed;
}

90
src/cli/index.ts Normal file
View File

@@ -0,0 +1,90 @@
import 'dotenv/config';
import { getDefaultConfig } from '../config/config';
import { createStats } from '../config/stats';
import { VisionProviderFactory } from '../providers/vision/visionProviderFactory';
import { TTSProviderFactory } from '../providers/tts/ttsProviderFactory';
import { generateAudioDescription } from '../utils/processor';
import { estimateCost } from '../utils/costEstimator';
import { loadConfigFromFile, saveConfigToFile } from '../utils/configUtils';
import { parseCommandLineArgs } from './args';
import { Config } from '../config/config';
async function main(): Promise<void> {
const argv = parseCommandLineArgs();
let config: Config = getDefaultConfig();
if (argv.config) {
const fileConfig = loadConfigFromFile(argv.config);
config = { ...config, ...fileConfig };
}
const argvObj = argv as unknown as Record<string, unknown>;
Object.keys(argvObj).forEach(key => {
if (key !== '_' && key !== '$0' && key !== 'config' && key !== 'saveConfig' &&
key !== 'estimate' && key !== 'help' && key !== 'version' &&
argvObj[key] !== undefined) {
(config as any)[key] = argvObj[key];
}
});
if (argv.visionModel) {
if (!config.visionProviders[config.visionProvider]) {
config.visionProviders[config.visionProvider] = { model: '' };
}
config.visionProviders[config.visionProvider].model = argv.visionModel;
}
if (argv.ttsModel) {
if (!config.ttsProviders[config.ttsProvider]) {
config.ttsProviders[config.ttsProvider] = { model: '' };
}
config.ttsProviders[config.ttsProvider].model = argv.ttsModel;
}
if (argv.ttsVoice) {
if (!config.ttsProviders[config.ttsProvider]) {
config.ttsProviders[config.ttsProvider] = { model: '', voice: '' };
}
config.ttsProviders[config.ttsProvider].voice = argv.ttsVoice;
}
if (argv.saveConfig) {
saveConfigToFile(argv.saveConfig, config);
}
if (argv._.length < 1) {
console.error('Error: No video file specified');
console.log('Usage: node script.js <video_file_path> [options]');
console.log('Use --help for more information');
process.exit(1);
}
const videoFilePath = String(argv._[0]);
if (argv.estimate) {
try {
const costBreakdown = await estimateCost(videoFilePath, config);
console.log('\n=== COST ESTIMATION ===');
console.log(JSON.stringify(costBreakdown, null, 2));
console.log(`\nEstimated total cost: ${costBreakdown.apiCosts.total}`);
console.log(`Estimated processing time: ${costBreakdown.estimates.estimatedProcessingTimeMinutes.toFixed(1)} minutes`);
console.log('Note: Actual costs may vary based on image complexity and actual response lengths.');
} catch (err) {
console.error('Error estimating costs:', err);
}
} else {
try {
const stats = createStats();
const visionProvider = VisionProviderFactory.getProvider(config);
const ttsProvider = TTSProviderFactory.getProvider(config);
await generateAudioDescription(videoFilePath, visionProvider, ttsProvider, config, stats);
} catch (err) {
console.error('Error generating audio description:', err);
}
}
}
if (require.main === module) {
main().catch(err => console.error('Unhandled error:', err));
}

99
src/config/config.ts
View File

@@ -30,54 +30,61 @@ export interface Config {
framesInBatch: number;
}
// Default configuration options
export const defaultConfig: Config = {
captureIntervalSeconds: 10,
contextWindowSize: 5,
defaultPrompt: "Describe this frame from a video in 1-2 sentences for someone who cannot see it. Focus on key visual elements. Avoid using terms like 'in this frame', simply describe the actual frame. Keep sentences short and concise, as this will be used to generate an audio track which is overlayed on the video.",
changePrompt: "Describe what has changed between these frames in 1-2 sentences for someone who cannot see the video. Focus on significant visual changes only. Avoid talking about meta information such as 'in this frame', or 'the significant change is', and merely describe the actual change taking place. Only describe the changes relevant to the last frame. The previous frames are attached for you to build context and build situational awareness. Keep it short and concise, as your text will be used to generate audio description tracks to be played with the video.",
batchPrompt: "Describe the sequence of frames in this batch over time for someone who cannot see it. Focus on what happens, changes, or stands out visually during these seconds. Keep it to 1-3 concise sentences, avoiding words like 'in these frames'—just describe what's happening. Use context from the previous batch if relevant. Keep sentences short and concise. Avoid speculation or overly verbose or unnecessary sentences. Try not to use nested sentences and keep sentences short to help flow. This will be used for audio description and mixed back in with the video file later, so we need to maintain consistency and quick pacing. Avoid using phrases such as 'as evidenced by' or 'suggesting'. Only focus on describing the visual scene. Do not repeat information given in the previous prompt, and focus only on what has changed since that description. Avoid talking about the scene or sequence, simply focus on the action within these frames. The listener knows that this is a video, so we do not need to remind them. Also avoid overusing phrases such as 'the scene shifts', the shifting or perspective change should be evident from the description of the sequence itself.",
/**
* Get default configuration options.
* Uses a function so that process.env is read at call time
* (after dotenv has been loaded), not at module import time.
*/
export function getDefaultConfig(): Config {
return {
captureIntervalSeconds: 10,
contextWindowSize: 5,
defaultPrompt: "Describe this frame from a video in 1-2 sentences for someone who cannot see it. Focus on key visual elements. Avoid using terms like 'in this frame', simply describe the actual frame. Keep sentences short and concise, as this will be used to generate an audio track which is overlayed on the video.",
changePrompt: "Describe what has changed between these frames in 1-2 sentences for someone who cannot see the video. Focus on significant visual changes only. Avoid talking about meta information such as 'in this frame', or 'the significant change is', and merely describe the actual change taking place. Only describe the changes relevant to the last frame. The previous frames are attached for you to build context and build situational awareness. Keep it short and concise, as your text will be used to generate audio description tracks to be played with the video.",
batchPrompt: "Describe the sequence of frames in this batch over time for someone who cannot see it. Focus on what happens, changes, or stands out visually during these seconds. Keep it to 1-3 concise sentences, avoiding words like 'in these frames'—just describe what's happening. Use context from the previous batch if relevant. Keep sentences short and concise. Avoid speculation or overly verbose or unnecessary sentences. Try not to use nested sentences and keep sentences short to help flow. This will be used for audio description and mixed back in with the video file later, so we need to maintain consistency and quick pacing. Avoid using phrases such as 'as evidenced by' or 'suggesting'. Only focus on describing the visual scene. Do not repeat information given in the previous prompt, and focus only on what has changed since that description. Avoid talking about the scene or sequence, simply focus on the action within these frames. The listener knows that this is a video, so we do not need to remind them. Also avoid overusing phrases such as 'the scene shifts', the shifting or perspective change should be evident from the description of the sequence itself.",
// Vision AI settings
visionProvider: "gemini",
visionModel: "gemini-2.0-flash",
visionProviders: {
openai: {
apiKey: process.env.OPENAI_API_KEY,
model: "gpt-4o",
maxTokens: 300
// Vision AI settings
visionProvider: "openai",
visionModel: "gpt-5.4-mini",
visionProviders: {
openai: {
apiKey: process.env.OPENAI_API_KEY,
model: "gpt-5.4-mini",
maxTokens: 300
},
gemini: {
apiKey: process.env.GOOGLE_API_KEY,
model: "gemini-2.0-flash",
maxTokens: 300
},
ollama: {
baseUrl: "http://localhost:11434",
model: "gemma3:12b",
maxTokens: 3000
}
},
gemini: {
apiKey: process.env.GOOGLE_API_KEY,
model: "gemini-2.0-flash",
maxTokens: 300
},
ollama: {
// Example config; adjust to match your local Ollama setup
baseUrl: "http://localhost:11434", // or wherever Ollama is hosted
model: "gemma3:12b",
maxTokens: 3000
}
// Add other vision providers here
},
// TTS settings
ttsProvider: "openai",
ttsVoice: "alloy", // Voice option for TTS
ttsSpeedFactor: 1.5, // Speed up audio by 50%
ttsProviders: {
openai: {
apiKey: process.env.OPENAI_API_KEY,
model: "tts-1-hd",
voice: "alloy"
// TTS settings
ttsProvider: "openai",
ttsVoice: "alloy",
ttsSpeedFactor: 1.5,
ttsProviders: {
openai: {
apiKey: process.env.OPENAI_API_KEY,
model: "tts-1-hd",
voice: "alloy"
}
},
// Add other TTS providers here
},
// Video processing settings
outputDir: "./desc/output/",
tempDir: "./desc/tmp/",
batchTimeMode: true, // Whether to use the new batch time mode
batchWindowDuration: 15, // How many seconds each batch covers
framesInBatch: 10, // How many frames to capture within each batch
};
// Video processing settings
outputDir: "./desc/output/",
tempDir: "./desc/tmp/",
batchTimeMode: true,
batchWindowDuration: 15,
framesInBatch: 10,
};
}
// Keep a static export alias for backward compatibility
// (but callers should prefer getDefaultConfig() for correct env loading)
export const defaultConfig = getDefaultConfig();

4
src/config/index.ts
View File

@@ -1,2 +1,2 @@
export * from './config';
export * from './stats';
export { Config, getDefaultConfig, defaultConfig } from './config';
export { createStats, printStats } from './stats';

37
src/config/stats.ts
View File

@@ -11,47 +11,30 @@ export const createStats = (): Stats => ({
totalCost: 0
});
// Pricing interface
interface PricingData {
vision: {
[provider: string]: {
[model: string]: {
input: number;
output: number;
}
}
};
tts: {
[provider: string]: {
[model: string]: number
}
};
}
// Pricing constants (as of March 2025)
const pricing: PricingData = {
const pricing: {
vision: Record<string, Record<string, { input: number; output: number }>>;
tts: Record<string, Record<string, number>>;
} = {
vision: {
openai: {
'gpt-4o': {
input: 0.0025, // per 1K input tokens
output: 0.01 // per 1K output tokens
input: 0.0025,
output: 0.01
}
// Add other OpenAI models here
},
gemini: {
'gemini-pro-vision': {
input: 0.0025, // per 1K input tokens
output: 0.0025 // per 1K output tokens
input: 0.0025,
output: 0.0025
}
}
// Add other vision providers here
},
tts: {
openai: {
'tts-1': 0.015, // per 1K characters
'tts-1-hd': 0.030 // per 1K characters
'tts-1': 0.015,
'tts-1-hd': 0.030
}
// Add other TTS providers here
}
};

86
src/index.ts
View File

@@ -1,5 +1,5 @@
import dotenv from 'dotenv';
import { defaultConfig } from './config/config';
import 'dotenv/config';
import { getDefaultConfig } from './config/config';
import { createStats } from './config/stats';
import { VisionProviderFactory } from './providers/vision/visionProviderFactory';
import { TTSProviderFactory } from './providers/tts/ttsProviderFactory';
@@ -7,72 +7,89 @@ import { generateAudioDescription } from './utils/processor';
import { estimateCost } from './utils/costEstimator';
import { loadConfigFromFile, saveConfigToFile } from './utils/configUtils';
import { parseCommandLineArgs } from './cli/args';
import { ProcessingResult, CostBreakdown } from './interfaces';
// Load environment variables
dotenv.config();
// Export functions and types for use as a module
export { generateAudioDescriptionFromOptions, generateAudioDescription } from './utils/processor';
export { estimateCost } from './utils/costEstimator';
export { getDefaultConfig, defaultConfig } from './config/config';
export { VisionProviderFactory } from './providers/vision/visionProviderFactory';
export { TTSProviderFactory } from './providers/tts/ttsProviderFactory';
export { createStats, printStats } from './config/stats';
export { loadConfigFromFile, saveConfigToFile } from './utils/configUtils';
export type { Config } from './config/config';
export type {
ProcessingResult,
CostBreakdown,
Stats,
VisionProvider,
TTSProvider,
AudioSegment,
BatchContext,
VisionResult,
TTSResult,
VisionProviderConfig,
TTSProviderConfig,
TTSOptions
} from './interfaces';
// CLI entry point when run directly
if (require.main === module) {
main().catch(err => console.error('Unhandled error:', err));
}
// Main execution when run directly
async function main(): Promise<void> {
// Parse command line arguments
const argv = parseCommandLineArgs();
// Start with default config
let config = { ...defaultConfig };
let config = getDefaultConfig();
// If a config file is specified, load it
if (argv.config) {
const fileConfig = loadConfigFromFile(argv.config);
config = { ...config, ...fileConfig };
}
// Override with any command line arguments
Object.keys(argv).forEach(key => {
const argvObj = argv as unknown as Record<string, unknown>;
Object.keys(argvObj).forEach(key => {
if (key !== '_' && key !== '$0' && key !== 'config' && key !== 'saveConfig' &&
key !== 'estimate' && key !== 'help' && key !== 'version' &&
argv[key as keyof typeof argv] !== undefined) {
(config as any)[key] = argv[key as keyof typeof argv];
argvObj[key] !== undefined) {
(config as any)[key] = argvObj[key];
}
});
// Handle nested provider configurations
if (argv.visionModel) {
if (!config.visionProviders[config.visionProvider]) {
config.visionProviders[config.visionProvider] = { model: '' };
}
config.visionProviders[config.visionProvider].model = argv.visionModel as string;
config.visionProviders[config.visionProvider].model = argv.visionModel;
}
if (argv.ttsModel) {
if (!config.ttsProviders[config.ttsProvider]) {
config.ttsProviders[config.ttsProvider] = { model: '' };
}
config.ttsProviders[config.ttsProvider].model = argv.ttsModel as string;
config.ttsProviders[config.ttsProvider].model = argv.ttsModel;
}
if (argv.ttsVoice) {
if (!config.ttsProviders[config.ttsProvider]) {
config.ttsProviders[config.ttsProvider] = { model: '', voice: '' };
}
config.ttsProviders[config.ttsProvider].voice = argv.ttsVoice as string;
config.ttsProviders[config.ttsProvider].voice = argv.ttsVoice;
}
// Save configuration if requested
if (argv.saveConfig) {
saveConfigToFile(argv.saveConfig as string, config);
saveConfigToFile(argv.saveConfig, config);
}
// Check if a video file is provided
if (argv._.length < 1) {
console.error('Error: No video file specified');
console.log('Usage: node script.js <video_file_path> [options]');
console.log('Usage: node dist/index.js <video_file_path> [options]');
console.log('Use --help for more information');
process.exit(1);
}
const videoFilePath = argv._[0] as string;
const videoFilePath = String(argv._[0]);
// Run estimation or full processing
if (argv.estimate) {
try {
const costBreakdown = await estimateCost(videoFilePath, config);
@@ -85,34 +102,13 @@ async function main(): Promise<void> {
console.error('Error estimating costs:', err);
}
} else {
// Run the full generator
try {
// Initialize the stats object
const stats = createStats();
// Initialize providers
const visionProvider = VisionProviderFactory.getProvider(config);
const ttsProvider = TTSProviderFactory.getProvider(config);
await generateAudioDescription(videoFilePath, visionProvider, ttsProvider, config, stats);
} catch (err) {
console.error('Error generating audio description:', err);
}
}
}
// Only run the main function if this file is executed directly (not imported)
if (require.main === module) {
main().catch(err => console.error('Unhandled error:', err));
}
// Export functions and types for use as a module
export {
generateAudioDescription,
estimateCost,
defaultConfig,
VisionProviderFactory,
TTSProviderFactory,
ProcessingResult,
CostBreakdown
};

13
src/providers/vision/geminiVisionProvider.ts
View File

@@ -1,25 +1,18 @@
import fs from 'fs';
import { GoogleGenerativeAI } from '@google/generative-ai';
import { VisionProvider, VisionProviderConfig, VisionResult, BatchContext } from '../../interfaces';
type GoogleGenerativeAI = any;
type GenerativeModel = any;
/**
* Google Gemini Vision Provider Implementation
*/
export class GeminiVisionProvider implements VisionProvider {
private config: VisionProviderConfig;
private genAI: GoogleGenerativeAI;
private model: GenerativeModel;
private model: any;
constructor(config: VisionProviderConfig) {
this.config = config;
// Import the Google Generative AI SDK
const { GoogleGenerativeAI } = require("@google/generative-ai");
// Initialize the API
this.genAI = new GoogleGenerativeAI(config.apiKey);
this.genAI = new GoogleGenerativeAI(config.apiKey!);
this.model = this.genAI.getGenerativeModel({ model: config.model });
}

6
src/providers/vision/openAIVisionProvider.ts
View File

@@ -44,7 +44,7 @@ export class OpenAIVisionProvider implements VisionProvider {
]
}
],
max_tokens: this.config.maxTokens || 300
max_completion_tokens: this.config.maxTokens || 300
});
return {
@@ -101,7 +101,7 @@ export class OpenAIVisionProvider implements VisionProvider {
]
}
],
max_tokens: this.config.maxTokens || 300
max_completion_tokens: this.config.maxTokens || 300
});
return {
@@ -171,7 +171,7 @@ export class OpenAIVisionProvider implements VisionProvider {
const response = await this.openai.chat.completions.create({
model: this.config.model,
messages,
max_tokens: this.config.maxTokens || 300
max_completion_tokens: this.config.maxTokens || 300
});
return {

22
src/utils/costEstimator.ts
View File

@@ -37,31 +37,29 @@ export async function estimateCost(
console.log(`Will process ${totalUnits} ${unitType}`);
// Pricing constants (as of March 2025, update as needed)
const pricing = {
// Get pricing based on vision provider
const pricing: {
vision: Record<string, Record<string, { input: number; output: number }>>;
tts: Record<string, Record<string, number>>;
} = {
vision: {
openai: {
'gpt-4o': {
input: 0.0025, // per 1K input tokens
output: 0.01 // per 1K output tokens
input: 0.0025,
output: 0.01
}
// Add other OpenAI models here
},
gemini: {
'gemini-pro-vision': {
input: 0.0025, // per 1K input tokens
output: 0.0025 // per 1K output tokens
input: 0.0025,
output: 0.0025
}
}
// Add other vision providers here
},
// Get pricing based on TTS provider
tts: {
openai: {
'tts-1': 0.015, // per 1K characters
'tts-1-hd': 0.030 // per 1K characters
'tts-1': 0.015,
'tts-1-hd': 0.030
}
// Add other TTS providers here
}
};

36
src/utils/processor.ts
View File

@@ -8,8 +8,10 @@ import {
BatchContext,
ProcessingResult
} from '../interfaces';
import { Config } from '../config/config';
import { printStats } from '../config/stats';
import { Config, getDefaultConfig } from '../config/config';
import { printStats, createStats } from '../config/stats';
import { VisionProviderFactory } from '../providers/vision/visionProviderFactory';
import { TTSProviderFactory } from '../providers/tts/ttsProviderFactory';
import {
getVideoDuration,
captureVideoFrame,
@@ -17,7 +19,35 @@ import {
} from './mediaUtils';
/**
* Generate audio description for a video
* High-level API: Generate audio description for a video with just options.
* This internally creates providers and stats so callers don't need to.
*
* @param videoFilePath - Path to the input video file
* @param options - Optional configuration overrides
* @returns Result of the operation
*/
export async function generateAudioDescriptionFromOptions(
videoFilePath: string,
options: Partial<Config> = {}
): Promise<ProcessingResult> {
const config = { ...getDefaultConfig(), ...options };
if (!fs.existsSync(config.tempDir)) {
fs.mkdirSync(config.tempDir, { recursive: true });
}
if (!fs.existsSync(config.outputDir)) {
fs.mkdirSync(config.outputDir, { recursive: true });
}
const visionProvider = VisionProviderFactory.getProvider(config);
const ttsProvider = TTSProviderFactory.getProvider(config);
const stats = createStats();
return generateAudioDescription(videoFilePath, visionProvider, ttsProvider, config, stats);
}
/**
* Generate audio description for a video (low-level API requiring pre-initialized providers).
* @param videoFilePath - Path to the input video file
* @param visionProvider - Vision provider instance
* @param ttsProvider - TTS provider instance