Trixy3/assets

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

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

# 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.