@umituz/react-native-media

Purpose

Advanced media management library for React Native applications. Provides media selection, upload, AI-powered generation, and flashcard multimedia support with Clean Architecture principles.

File Location

Project root: /README.md

Strategy

• Provide comprehensive media handling for React Native applications
• Support both general media operations and card-specific features
• Enable AI-powered media generation (text-to-image, text-to-audio, image-search)
• Maintain Clean Architecture with clear separation of concerns
• Offer React Hooks for easy integration
• Follow singleton pattern for services
• Provide TypeScript types for type safety
• Support Expo ecosystem (expo-image-picker, expo-media-library)

Forbidden

• DO NOT use this library without proper permissions handling
• DO NOT upload files without validation
• DO NOT ignore file size limits
• DO NOT use general media features for card-specific requirements
• DO NOT mix card and general media types interchangeably
• DO NOT bypass singleton pattern for services
• DO NOT ignore error handling from services/hooks
• DO NOT use deprecated APIs

Rules

1. Always check permissions before accessing camera/gallery
2. Always validate files before upload
3. Always handle loading and error states
4. Use hooks for React components, services for non-React code
5. Follow position rules for card media (FRONT, BACK, BOTH)
6. Respect file size limits (images: 10 MB, videos: 100 MB)
7. Use appropriate quality levels for compression
8. Handle all three generation types correctly (text_to_image, text_to_audio, image_search)
9. Always check canceled flag in picker results
10. Import from main entry point only

AI Agent Guidelines

Installation Requirements

Before using this library, ensure:

• expo-image-picker (>=14.0.0) is installed
• expo-media-library (>=15.0.0) is installed
• Peer dependencies are met:
  • @umituz/react-native-design-system
  • @umituz/react-native-filesystem
  • @umituz/react-native-image
  • react (>=18.2.0)
  • react-native (>=0.74.0)

Feature Selection Guidelines

Use General Media Features When:

• Building standard media handling features
• No card/flashcard requirements exist
• Basic upload/download/validation needed
• General-purpose media operations

Use Card-Specific Features When:

• Building flashcard applications
• Position-based media needed (front/back/both)
• Working with card entities
• Need card-specific validation rules
• Using card generation with +image-search

Permission Management

All media operations require proper permissions:

• Camera access requires user permission
• Gallery access requires user permission
• Save to gallery requires write permission
• Always handle permission denial gracefully
• Provide clear UI for permission requests

Module Structure

Domain Layer

• Location: src/domain/
• Purpose: Core types and business logic
• Contains: Media entities, enums, interfaces, utilities
• Dependency: External library agnostic

Infrastructure Layer

• Location: src/infrastructure/
• Purpose: Service implementations and external integrations
• Contains: Services for picker, upload, generation, validation, optimization
• Dependency: Uses expo libraries and external APIs

Presentation Layer

• Location: src/presentation/
• Purpose: React hooks for UI integration
• Contains: All use* hooks for React components
• Dependency: Wraps infrastructure services

Service Pattern

All services follow singleton pattern:

• Access via getInstance() method
• Single instance throughout application
• Static methods for direct access
• Thread-safe operations

Hook Usage

Best practices for using hooks:

• Use hooks in React components only
• Follow naming convention (use*)
• Handle loading states appropriately
• Handle error states appropriately
• Use progress callbacks when available
• Destructure hook returns for clarity

Media Type Guidelines

General Media Types

• MediaType.IMAGE - For images only
• MediaType.VIDEO - For videos only
• MediaType.ALL - For all media types

Card Media Positions

• CardMediaPosition.FRONT - Media on card front
• CardMediaPosition.BACK - Media on card back
• CardMediaPosition.BOTH - Media on both sides

Generation Types

• text_to_image - Generate images from text
• text_to_audio - Generate audio from text
• image_search - Search for images (card-specific only)

Validation Rules

File Size Limits

• Images: Maximum 10 MB
• Videos: Maximum 100 MB
• Card media: Stricter limits apply

Supported Formats

• Images: JPEG, PNG, WEBP, GIF
• Videos: MP4, MOV
• Audio: MP3, WAV, AAC

Quality Levels

• LOW: 0.3 (30% quality)
• MEDIUM: 0.7 (70% quality)
• HIGH: 1.0 (100% quality)
• ORIGINAL: No compression

Error Handling

Always handle these error scenarios:

• Permission denied
• File too large
• Invalid format
• Network timeout
• Upload failure
• Generation failure (insufficient credits)
• Validation errors

Import Strategy

Import from main entry point only:

• Services: Import by name
• Hooks: Import by name
• Types: Use import type for tree-shaking

Recommended patterns:

• Import specific items you need
• Avoid wildcard imports
• Separate type imports
• Use named exports only

Documentation Structure

For detailed information about specific features, refer to:

Domain Layer

• Media Entities - Core types and interfaces
• CardMultimedia Types - Card-specific types
• MultimediaFlashcard Types - Flashcard types
• MediaUtils - Domain utilities

Infrastructure Services

• MediaPickerService - Camera and gallery
• MediaSaveService - Save to gallery
• MediaUploadService - Upload/download
• MediaGenerationService - AI generation
• MediaValidationService - Validation
• MediaOptimizerService - Optimization
• CardMultimediaService - Card operations
• CardMediaGenerationService - Card AI generation
• CardMediaUploadService - Card upload
• CardMediaValidationService - Card validation
• CardMediaOptimizerService - Card optimization
• MultimediaFlashcardService - Flashcard service
• CardMultimediaFlashcardService - Card flashcard service

Infrastructure Utils

• Media Helpers - Helper functions
• Media Picker Mappers - Mapper functions

Presentation Hooks

• useMedia - Media selection
• useMediaUpload - Upload with progress
• useMediaGeneration - AI generation
• useMediaValidation - Validation
• useMultimediaFlashcard - Flashcard creation
• useCardMultimediaFlashcard - Card management
• useCardMediaGeneration - Card AI generation
• useCardMediaUpload - Card upload
• useCardMediaValidation - Card validation

Presentation Types

• Card Multimedia Hook Types - Card hook types
• Multimedia Hook Types - General hook types

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Ümit UZ

• Website: umituz.com
• GitHub: @umituz

Acknowledgments

• Expo team for expo-image-picker and expo-media-library
• React Native community

Support

For issues and questions, please use GitHub Issues.

Related Projects

• @umituz/react-native-design-system
• @umituz/react-native-filesystem
• @umituz/react-native-image