ReviewOS

also looking at this

stacks/ts-aax

chore: enhance logging

#55
Merged cab-mikee wants to merge chore/enhance-logging into main
12 files +379 -9
.cursor/rules/readme.mdcadded+198-0
Changes to .cursor/rules/readme.mdc
@@ -0,0 +1,198 @@
1---
2description: General information based on the latest ./README.md content
3globs:
4---
5Update it if APIs change:
6
7# AAX Audio Converter
8
9A TypeScript library and CLI tool for converting Audible AAX audiobooks to standard MP3, M4A, or M4B formats.
10
11![Screenshot](.github/art/screenshot.png)
12
13## Features
14
15- Convert AAX files to MP3, M4A, or M4B formats
16- Preserve chapter information
17- Automatically detect Audible activation code
18- Split audiobooks by chapters
19- Simple command-line interface
20
21## Installation
22
23```bash
24# Install globally
25npm install -g @stacksjs/aax
26
27# Or use with npx
28npx @stacksjs/aax
29```
30
31## Requirements
32
33- `ffmpeg` & [`audible`](https://github.com/mkb79/audible-cli) must be installed and available in your PATH
34
35_Please read [Using the Audible CLI Integration](#using-the-audible-cli-integration) for more information._
36
37## CLI Usage
38
39### Convert an AAX file to MP3
40
41```bash
42aax convert /path/to/audiobook.aax
43```
44
45### Convert with custom options
46
47```bash
48aax convert /path/to/audiobook.aax --format m4b --output ./my-audiobooks --bitrate 192
49```
50
51### Convert and split by chapters
52
53```bash
54aax split /path/to/audiobook.aax
55```
56
57### Available CLI Options
58
59- `-o, --output <dir>` - Output directory (default: ./converted)
60- `-f, --format <format>` - Output format: mp3, m4a, m4b (default: mp3)
61- `-c, --code <code>` - Audible activation code (auto-detected if not provided)
62- `--chapters` - Preserve chapter information (default: true)
63- `-b, --bitrate <kbps>` - Audio bitrate in kbps (default: 'source' to match the original file)
64- `-v, --verbose` - Enable verbose logging
65- `--flat-folder-structure` - Use flat folder structure
66- `--series-title-in-folder-structure` - Include series title in folder structure
67- `--variable-bit-rate` - Apply variable bit rate
68- `--aac-encoding-44-1` - Fix AAC encoding for 44.1 kHz
69- `--use-named-chapters` - Use named chapters if available
70- `--skip-short-chapters-duration <seconds>` - Skip short chapters between book parts
71- `--skip-very-short-chapter-duration <seconds>` - Skip very short chapters at begin and end
72
73## Library Usage
74
75```typescript
76import { convertAAX } from 'aax'
77
78async function convertBook() {
79 const result = await convertAAX({
80 inputFile: '/path/to/audiobook.aax',
81 outputFormat: 'mp3',
82 outputDir: './converted',
83 chaptersEnabled: true,
84 bitrate: 128,
85 })
86
87 if (result.success) {
88 console.log(`Conversion complete: ${result.outputPath}`)
89 }
90 else {
91 console.error(`Conversion failed: ${result.error}`)
92 }
93}
94```
95
96## Configuration
97
98You can create an `aax.config.ts` or `aax.config.js` file in your project root to customize default settings:
99
100```typescript
101export default {
102 verbose: true,
103 outputFormat: 'mp3',
104 outputDir: './my-audiobooks',
105 chaptersEnabled: true,
106 bitrate: 192,
107 // Optional: manually set the activation code
108 // activationCode: '1a2b3c4d',
109 // Optional: specify a custom FFmpeg path
110 // ffmpegPath: '/usr/local/bin/ffmpeg',
111 // New options
112 flatFolderStructure: false,
113 seriesTitleInFolderStructure: true,
114 fullCaptionForBookFolder: false,
115 partFolderPrefix: 'standard',
116 sequenceNumberDigits: 2,
117 customSearchWords: [],
118 additionalPunctuation: '',
119 intermediateFileCopy: false,
120 aacEncoding44_1: false,
121 variableBitRate: false,
122 reduceBitRate: 'no',
123 fileType: 'm4a',
124 useISOLatin1: false,
125 extractCoverImage: true,
126 useNamedChapters: true,
127 skipShortChaptersDuration: 25,
128 skipVeryShortChapterDuration: 10,
129 verifyChapterMarks: 'all',
130 preferEmbeddedChapterTimes: true,
131}
132```
133
134## Using the Audible CLI Integration
135
136This tool integrates with the Audible CLI to automatically retrieve activation bytes (activation codes) from Audible's servers using your account credentials. This makes it much easier to convert your AAX audiobooks without manually finding activation codes.
137
138### Prerequisites
139
1401. Download the Audible CLI binary and place it in the root of your project:
141 - [Audible CLI Releases](https://github.com/mkb79/audible-cli/releases)
142 - Choose the appropriate version for your OS (e.g., `audible-cli-0.2.0-windows-amd64.exe` for Windows)
143 - Rename it to `audible` and place it in the project root
144
145### Setting up Audible CLI
146
147Run the setup command:
148
149```bash
150aax setup-audible
151```
152
153This will:
154
1551. Check if the audible binary exists
1562. Make it executable
1573. Run the quickstart wizard (you'll need to follow the interactive prompts to log in to your Audible account)
1584. Retrieve your activation bytes from Audible's servers
1595. Save them for future use
160
161During the setup process, you'll see something like this:
162
163```
164Setting up Audible CLI and retrieving activation bytes...
165Note: You may be prompted to log in to your Audible account.
166Follow the prompts in the terminal to complete the setup.
167
168Attempting to get activation bytes from Audible CLI...
169Audible CLI is not configured. Setting up...
170Starting Audible CLI quickstart. Please follow the prompts to log in to your Audible account.
171# ... (interactive login process) ...
172
173Fetching activation bytes from Audible server...
174✅ Found activation bytes from Audible CLI: 2c******
175
176✅ Successfully retrieved activation bytes: 2c******
177
178You can now use this activation code with the convert command:
179aax convert your-audiobook.aax -c 2c1eeb0a
180
181The activation code has been saved and will be used automatically for future conversions.
182```
183
184Once set up, your activation code will be automatically used for all future conversions, so you don't need to specify it manually.
185
186### Manual Setup (if the automated setup fails)
187
188If the automated setup fails, you can do it manually:
189
1901. Run: `./audible quickstart`
1912. Follow the prompts to log in to your Audible account
1923. Once set up, run: `./audible activation-bytes`
1934. Note the activation code (a 8-character hex string like `2c1eeb0a`)
1945. Use this code with the convert command:
195
196 ```bash
197 aax convert your-audiobook.aax -c YOUR_ACTIVATION_CODE
198 ```