# Trixy Assets Directory

This directory contains all assets used by the Trixy voice assistant application, organized using a profile-based system for different deployment environments and use cases.

## Directory Structure

```
assets/
├── README.md                    # This file
├── default/                     # Default asset profile (fallback)
│   ├── audio/                   # Audio assets
│   │   ├── success.wav         # Success notification sound
│   │   ├── error.wav           # Error notification sound
│   │   ├── notification.wav    # General notification sound
│   │   └── wakeword_detected.wav # Wakeword confirmation sound
│   ├── images/                  # Image assets
│   │   ├── icon_connected.png   # Connected status icon
│   │   ├── icon_disconnected.png # Disconnected status icon
│   │   ├── icon_listening.png   # Listening status icon
│   │   └── icon_processing.png  # Processing status icon
│   ├── text/                    # Text assets
│   │   ├── welcome_message.txt  # Welcome message template
│   │   ├── error_messages.json  # Error message templates
│   │   └── response_templates.yaml # Response templates
│   └── config/                  # Configuration assets
│       ├── asset_profiles.json  # Asset profile configurations
│       └── validation_rules.yaml # Validation rules
└── [other_profiles]/           # Additional profiles (production, development, etc.)
```

## Asset Resolution System

The Trixy asset management system uses profile-based resolution with fallback:

1. **Primary Path**: `./assets/{profile}/path/to/asset`
2. **Fallback Path**: `./assets/default/path/to/asset`
3. **Not Found**: Returns `False` if asset not found in either location

### Example

If the current profile is "production" and you request `audio/success.wav`:

1. First checks: `./assets/production/audio/success.wav`
2. If not found, checks: `./assets/default/audio/success.wav`
3. If still not found, returns `False`

## Asset Profiles

### Default Profile
- **Purpose**: Base assets used as fallback for all other profiles
- **Characteristics**: Standard quality, universal compatibility
- **Required**: Yes (must always exist)

### Production Profile
- **Purpose**: Optimized assets for production deployment
- **Characteristics**: Compressed, optimized for performance
- **Location**: `./assets/production/`

### Development Profile
- **Purpose**: Assets for development and testing
- **Characteristics**: Uncompressed, with debug information
- **Location**: `./assets/development/`

### Testing Profile
- **Purpose**: Assets for automated testing and CI/CD
- **Characteristics**: Minimal size, fast loading
- **Location**: `./assets/testing/`

## Asset Types

### Audio Assets
- **Formats**: WAV (primary), MP3, OGG, FLAC
- **Specifications**: 
  - Sample Rate: 44.1kHz or 48kHz
  - Channels: Mono or Stereo
  - Bit Depth: 16-bit or 24-bit
- **Use Cases**: Notifications, confirmations, alerts

### Image Assets  
- **Formats**: PNG (primary), JPEG, GIF, SVG
- **Specifications**:
  - Max Resolution: 2048x2048 pixels
  - Color Depth: 32-bit (RGBA) for PNG
  - Transparency: Supported for PNG/GIF
- **Use Cases**: Icons, status indicators, UI elements

### Text Assets
- **Formats**: TXT, JSON, YAML, Markdown
- **Encoding**: UTF-8 (required)
- **Use Cases**: Templates, messages, responses, documentation

### Configuration Assets
- **Formats**: JSON (primary), YAML
- **Purpose**: Asset profiles, validation rules, metadata
- **Schema**: Validated against predefined schemas

## Usage Examples

### In Python Code

```python
from trixy_core.assets import AssetManager

# Get asset manager from application container
asset_manager = application.get_asset_manager()

# Get asset path (main API method)
success_sound = asset_manager.get_path("audio/success.wav")
if success_sound:
    # Use the asset file
    play_sound(success_sound)
else:
    # Asset not found, handle gracefully
    log_warning("Success sound not found")

# Get other assets
error_icon = asset_manager.get_path("images/icon_error.png")
welcome_text = asset_manager.get_path("text/welcome_message.txt")
```

### With Different Profiles

```python
# Set profile for the session
asset_manager.set_profile("production")

# Assets will now be loaded from production profile first,
# with fallback to default profile
optimized_sound = asset_manager.get_path("audio/notification.wav")
```

## Asset Management Features

### Caching
- **Memory Cache**: Fast access to frequently used assets
- **Disk Cache**: Persistent cache across application restarts
- **Compression**: Optional compression to reduce memory usage
- **LRU Eviction**: Least recently used assets evicted first

### Validation
- **Format Validation**: Ensures assets match expected formats
- **Integrity Checking**: SHA256 checksums for corruption detection
- **Size Constraints**: Enforces maximum/minimum file sizes
- **Security Scanning**: Basic security checks for text-based assets

### Hot Reload (Development)
- **File Watching**: Automatic detection of asset changes
- **Cache Invalidation**: Modified assets automatically reloaded
- **Debouncing**: Prevents excessive reloads during rapid changes

## Creating New Profiles

To create a new asset profile:

1. **Create Directory**: `mkdir assets/my_profile`
2. **Add Assets**: Copy or create assets in the new profile directory
3. **Configure Profile**: Update `config/asset_profiles.json` if needed
4. **Set Profile**: Use `asset_manager.set_profile("my_profile")` in code

Example profile structure:
```
assets/my_profile/
├── audio/
│   └── custom_notification.wav
├── images/
│   └── custom_icon.png
└── text/
    └── custom_messages.json
```

## Asset Naming Conventions

### Audio Assets
- `success.wav` - Success confirmation sound
- `error.wav` - Error notification sound  
- `notification.wav` - General notification
- `wakeword_detected.wav` - Wakeword confirmation
- `{action}_{result}.wav` - Action-specific sounds

### Image Assets
- `icon_{status}.png` - Status indicator icons
- `button_{action}.png` - UI button icons
- `logo_{variant}.png` - Logo variations
- `bg_{context}.png` - Background images

### Text Assets
- `{purpose}_message.txt` - Simple text messages
- `{category}_templates.json` - Structured templates
- `{type}_responses.yaml` - Response templates

## Performance Considerations

### File Sizes
- **Audio**: Keep under 1MB for notifications
- **Images**: Keep under 100KB for icons
- **Text**: Keep under 100KB for templates

### Optimization Tips
1. Use appropriate formats (PNG for icons, JPEG for photos)
2. Compress images without quality loss
3. Use mono audio for voice notifications
4. Minimize JSON/YAML file sizes
5. Enable asset caching in production

## Troubleshooting

### Asset Not Found
1. Check file exists in profile directory
2. Check file exists in default directory  
3. Verify file permissions are readable
4. Check asset path uses forward slashes (`/`)

### Performance Issues
1. Enable asset caching
2. Optimize large asset files
3. Use appropriate asset profiles
4. Monitor cache hit rates

### Validation Errors
1. Check asset format matches expectations
2. Verify file is not corrupted
3. Review validation rules configuration
4. Check file encoding (UTF-8 for text)

## Best Practices

1. **Always provide defaults**: Every asset should exist in default profile
2. **Use consistent naming**: Follow naming conventions for easy management
3. **Optimize for target**: Use appropriate asset profiles for deployment
4. **Test thoroughly**: Validate assets before deployment
5. **Monitor performance**: Track asset loading times and cache performance
6. **Version control**: Keep assets in version control with appropriate `.gitignore` rules
7. **Document changes**: Update this README when adding new asset types or profiles

## Contributing

When adding new assets:

1. Add to `default/` profile first
2. Create optimized versions for other profiles if needed
3. Update validation rules if new asset types are added
4. Test with asset management system
5. Update documentation

For questions or issues with the asset management system, refer to the main Trixy documentation or contact the development team.