Skip to content

Commit 02d02f6

Browse files
cab-mikeecab-mikee
committed
chore: add features and advances
1 parent f20d47e commit 02d02f6

File tree

7 files changed

+862
-14
lines changed

7 files changed

+862
-14
lines changed

‎docs/.vitepress/config.ts‎

Lines changed: 20 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
import type { HeadConfig } from 'vitepress'
2-
import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
32
import { withPwa } from '@vite-pwa/vitepress'
43
import { defineConfig } from 'vitepress'
54

@@ -60,8 +59,26 @@ const sidebar = [
6059
{ text: 'Config', link: '/config' },
6160
],
6261
},
63-
{ text: 'Showcase', link: '/Showcase' },
62+
{
63+
text: 'Features',
64+
items: [
65+
{ text: 'Overview', link: '/features/' },
66+
{ text: 'Audio Conversion', link: '/features/audio-conversion' },
67+
{ text: 'CLI Usage', link: '/features/cli-usage' },
68+
],
69+
},
70+
{
71+
text: 'Advanced',
72+
items: [
73+
{ text: 'Overview', link: '/advanced/' },
74+
{ text: 'Stream Processing', link: '/advanced/stream-processing' },
75+
{ text: 'Metadata Handling', link: '/advanced/metadata-handling' },
76+
],
77+
},
78+
{ text: 'API Reference', link: '/api-reference' },
79+
{ text: 'Showcase', link: '/showcase' },
6480
]
81+
6582
const description = 'A modern, fast reverse proxy. For a better local development environment.'
6683
const title = 'audiox | A modern, fast reverse proxy. For a better local development environment.'
6784

@@ -93,7 +110,7 @@ export default withPwa(
93110

94111
['meta', { property: 'og:site_name', content: 'audiox' }],
95112
['meta', { property: 'og:image', content: './images/og-image.jpg' }],
96-
['meta', { property: 'og:url', content: 'https://reverse-proxy.sh/' }],
113+
['meta', { property: 'og:url', content: 'stacks-audiox.netlify.app' }],
97114
// ['script', { 'src': 'https://cdn.usefathom.com/script.js', 'data-site': '', 'data-spa': 'auto', 'defer': '' }],
98115
...analyticsHead,
99116
],
@@ -126,13 +143,6 @@ export default withPwa(
126143
{ icon: 'github', link: 'https://github.com/stacksjs/audiox' },
127144
{ icon: 'discord', link: 'https://discord.gg/stacksjs' },
128145
],
129-
130-
// algolia: services.algolia,
131-
132-
// carbonAds: {
133-
// code: '',
134-
// placement: '',
135-
// },
136146
},
137147

138148
pwa: {
@@ -146,10 +156,6 @@ export default withPwa(
146156
light: 'github-light',
147157
dark: 'github-dark',
148158
},
149-
150-
codeTransformers: [
151-
transformerTwoslash(),
152-
],
153159
},
154160

155161
vite,

‎docs/advanced/index.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Advanced Topics
2+
3+
Welcome to the advanced documentation for AudioX. This section covers in-depth technical details and advanced usage patterns for getting the most out of AudioX.
4+
5+
## Available Topics
6+
7+
### [Stream Processing](./stream-processing.md)
8+
9+
Advanced techniques for handling audio streams, including:
10+
11+
- Input/Output stream handling
12+
- Memory management
13+
- Performance optimization
14+
- Real-time processing
15+
- Custom transformations
16+
17+
### [Metadata Handling](./metadata-handling.md)
18+
19+
Comprehensive guide to working with audio metadata:
20+
21+
- Standard and custom metadata fields
22+
- Reading and writing metadata
23+
- Batch operations
24+
- Custom metadata schemas
25+
- Automated metadata management
26+
27+
## Coming Soon
28+
29+
### Performance Optimization
30+
31+
- CPU and memory optimization
32+
- Parallel processing
33+
- Caching strategies
34+
- Resource management
35+
36+
### Custom Plugins
37+
38+
- Creating custom audio processors
39+
- Plugin architecture
40+
- Integration patterns
41+
- Event handling
42+
43+
### Error Handling
44+
45+
- Advanced error recovery
46+
- Debugging techniques
47+
- Logging and monitoring
48+
- Error prevention strategies
49+
50+
### CLI Advanced Usage
51+
52+
- Custom commands
53+
- Automation scripts
54+
- Configuration management
55+
- Integration patterns
56+
57+
## Best Practices
58+
59+
When working with advanced features, keep these principles in mind:
60+
61+
1. **Performance First**
62+
- Always consider memory usage
63+
- Implement proper cleanup
64+
- Use appropriate buffer sizes
65+
66+
2. **Error Handling**
67+
- Implement comprehensive error handling
68+
- Use appropriate recovery strategies
69+
- Log errors effectively
70+
71+
3. **Resource Management**
72+
- Clean up resources properly
73+
- Monitor system resources
74+
- Implement proper timeouts
75+
76+
4. **Code Organization**
77+
- Follow TypeScript best practices
78+
- Maintain clear documentation
79+
- Use consistent patterns
80+
81+
## Contributing
82+
83+
We welcome contributions to these advanced guides! If you have expertise in any of these areas or would like to suggest new topics, please:
84+
85+
1. Check our [Contributing Guide](https://github.com/stacksjs/contributing)
86+
2. Submit a PR with your changes
87+
3. Ensure proper documentation
88+
4. Include examples and use cases
89+
90+
## Support
91+
92+
If you need help with these advanced topics:
93+
94+
- Join our [Discord Community](https://discord.gg/stacksjs)
95+
- Check our [GitHub Discussions](https://github.com/stacksjs/stacks/discussions)
96+
- Review our [Issue Tracker](https://github.com/stacksjs/audiox/issues)

‎docs/advanced/metadata-handling.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Advanced Metadata Handling
2+
3+
## Understanding Audio Metadata
4+
5+
AudioX provides comprehensive tools for reading, writing, and manipulating audio file metadata. This guide covers advanced metadata handling techniques and best practices.
6+
7+
## Metadata Types
8+
9+
### Standard Metadata Fields
10+
11+
```typescript
12+
interface AudioMetadata {
13+
title?: string
14+
artist?: string
15+
album?: string
16+
year?: string
17+
genre?: string
18+
track?: string
19+
composer?: string
20+
copyright?: string
21+
description?: string
22+
}
23+
```
24+
25+
### Custom Metadata
26+
27+
```typescript
28+
// Adding custom metadata
29+
await audio('input.mp3', 'output.mp3', {
30+
metadata: {
31+
custom_field: 'value',
32+
processing_date: new Date().toISOString(),
33+
source_quality: 'studio',
34+
}
35+
})
36+
```
37+
38+
## Reading Metadata
39+
40+
### Basic Metadata Reading
41+
42+
```typescript
43+
import { getAudioInfo } from '@stacksjs/audiox'
44+
45+
const info = await getAudioInfo('audio.mp3')
46+
console.log(info.metadata) // Access standard metadata
47+
```
48+
49+
### Advanced Metadata Extraction
50+
51+
```typescript
52+
// Reading specific metadata tags
53+
const info = await getAudioInfo('audio.mp3', {
54+
metadataTags: ['title', 'artist', 'custom_field']
55+
})
56+
```
57+
58+
## Writing Metadata
59+
60+
### Metadata Preservation
61+
62+
```typescript
63+
// Preserve existing metadata while converting
64+
await audio('input.mp3', 'output.wav', {
65+
preserveMetadata: true,
66+
metadata: {
67+
// Add or override specific fields
68+
processing_tool: 'audiox',
69+
}
70+
})
71+
```
72+
73+
### Batch Metadata Updates
74+
75+
```typescript
76+
// Update metadata for multiple files
77+
async function updateBatchMetadata(files: string[], metadata: AudioMetadata) {
78+
for (const file of files) {
79+
await audio(file, file, {
80+
metadata,
81+
preserveExisting: true,
82+
})
83+
}
84+
}
85+
```
86+
87+
## Metadata Manipulation
88+
89+
### Metadata Transformation
90+
91+
```typescript
92+
// Transform metadata during processing
93+
function transformMetadata(original: AudioMetadata): AudioMetadata {
94+
return {
95+
...original,
96+
title: `${original.title} (Processed)`,
97+
processing_date: new Date().toISOString(),
98+
}
99+
}
100+
```
101+
102+
### Metadata Validation
103+
104+
```typescript
105+
// Validate metadata before writing
106+
function validateMetadata(metadata: AudioMetadata): boolean {
107+
const required = ['title', 'artist']
108+
return required.every(field => metadata[field]?.length > 0)
109+
}
110+
```
111+
112+
## Best Practices
113+
114+
### Metadata Handling
115+
116+
1. Always validate metadata before writing
117+
2. Preserve important existing metadata
118+
3. Use consistent naming conventions
119+
4. Handle missing metadata gracefully
120+
121+
### Performance Considerations
122+
123+
1. Batch metadata operations when possible
124+
2. Cache metadata for frequently accessed files
125+
3. Implement proper error handling
126+
4. Use appropriate metadata field types
127+
128+
## Advanced Use Cases
129+
130+
### Automated Metadata Management
131+
132+
```typescript
133+
// Automatically manage metadata based on file content
134+
async function autoMetadata(file: string) {
135+
const info = await getAudioInfo(file)
136+
137+
return {
138+
title: generateTitle(info),
139+
artist: extractArtist(info),
140+
quality: determineQuality(info),
141+
processed_by: 'audiox',
142+
processing_date: new Date().toISOString(),
143+
}
144+
}
145+
```
146+
147+
### Custom Metadata Schemas
148+
149+
```typescript
150+
// Implement custom metadata schemas
151+
interface CustomAudioMetadata extends AudioMetadata {
152+
processing: {
153+
tool: string
154+
version: string
155+
date: string
156+
settings: Record<string, unknown>
157+
}
158+
quality: {
159+
original: string
160+
processed: string
161+
improvement: number
162+
}
163+
}
164+
```

0 commit comments

Comments
 (0)