claudeguide-engineer 1.14.8

package/.claude/skills/media-processing/scripts/video_optimize.py

@@ -0,0 +1,414 @@
+#!/usr/bin/env python3
+"""
+Video size optimization with quality/size balance.
+
+Supports resolution reduction, frame rate adjustment, audio bitrate optimization,
+multi-pass encoding, and comparison metrics.
+"""
+
+import argparse
+import json
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+@dataclass
+class VideoInfo:
+    """Video file information."""
+    path: Path
+    duration: float
+    width: int
+    height: int
+    bitrate: int
+    fps: float
+    size: int
+    codec: str
+    audio_codec: str
+    audio_bitrate: int
+
+
+class VideoOptimizer:
+    """Handle video optimization operations using FFmpeg."""
+
+    def __init__(self, verbose: bool = False, dry_run: bool = False):
+        self.verbose = verbose
+        self.dry_run = dry_run
+
+    def check_ffmpeg(self) -> bool:
+        """Check if FFmpeg is available."""
+        try:
+            subprocess.run(
+                ['ffmpeg', '-version'],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                check=True
+            )
+            return True
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return False
+
+    def get_video_info(self, input_path: Path) -> Optional[VideoInfo]:
+        """Extract video information using ffprobe."""
+        try:
+            cmd = [
+                'ffprobe',
+                '-v', 'quiet',
+                '-print_format', 'json',
+                '-show_format',
+                '-show_streams',
+                str(input_path)
+            ]
+
+            result = subprocess.run(cmd, capture_output=True, check=True)
+            data = json.loads(result.stdout)
+
+            # Find video and audio streams
+            video_stream = None
+            audio_stream = None
+
+            for stream in data['streams']:
+                if stream['codec_type'] == 'video' and not video_stream:
+                    video_stream = stream
+                elif stream['codec_type'] == 'audio' and not audio_stream:
+                    audio_stream = stream
+
+            if not video_stream:
+                return None
+
+            # Parse frame rate
+            fps_parts = video_stream.get('r_frame_rate', '0/1').split('/')
+            fps = float(fps_parts[0]) / float(fps_parts[1]) if len(fps_parts) == 2 else 0
+
+            return VideoInfo(
+                path=input_path,
+                duration=float(data['format'].get('duration', 0)),
+                width=int(video_stream.get('width', 0)),
+                height=int(video_stream.get('height', 0)),
+                bitrate=int(data['format'].get('bit_rate', 0)),
+                fps=fps,
+                size=int(data['format'].get('size', 0)),
+                codec=video_stream.get('codec_name', 'unknown'),
+                audio_codec=audio_stream.get('codec_name', 'none') if audio_stream else 'none',
+                audio_bitrate=int(audio_stream.get('bit_rate', 0)) if audio_stream else 0
+            )
+
+        except Exception as e:
+            print(f"Error getting video info: {e}", file=sys.stderr)
+            return None
+
+    def calculate_target_resolution(
+        self,
+        width: int,
+        height: int,
+        max_width: Optional[int],
+        max_height: Optional[int]
+    ) -> Tuple[int, int]:
+        """Calculate target resolution maintaining aspect ratio."""
+        if not max_width and not max_height:
+            return width, height
+
+        aspect_ratio = width / height
+
+        if max_width and max_height:
+            # Fit within both constraints
+            if width > max_width or height > max_height:
+                if width / max_width > height / max_height:
+                    new_width = max_width
+                    new_height = int(max_width / aspect_ratio)
+                else:
+                    new_height = max_height
+                    new_width = int(max_height * aspect_ratio)
+            else:
+                new_width, new_height = width, height
+        elif max_width:
+            new_width = min(width, max_width)
+            new_height = int(new_width / aspect_ratio)
+        else:
+            new_height = min(height, max_height)
+            new_width = int(new_height * aspect_ratio)
+
+        # Ensure dimensions are even (required by some codecs)
+        new_width = new_width - (new_width % 2)
+        new_height = new_height - (new_height % 2)
+
+        return new_width, new_height
+
+    def optimize_video(
+        self,
+        input_path: Path,
+        output_path: Path,
+        max_width: Optional[int] = None,
+        max_height: Optional[int] = None,
+        target_fps: Optional[float] = None,
+        crf: int = 23,
+        audio_bitrate: str = '128k',
+        preset: str = 'medium',
+        two_pass: bool = False
+    ) -> bool:
+        """Optimize a video file."""
+        # Get input video info
+        info = self.get_video_info(input_path)
+        if not info:
+            print(f"Error: Could not read video info for {input_path}", file=sys.stderr)
+            return False
+
+        if self.verbose:
+            print(f"\nInput video info:")
+            print(f"  Resolution: {info.width}x{info.height}")
+            print(f"  FPS: {info.fps:.2f}")
+            print(f"  Bitrate: {info.bitrate // 1000} kbps")
+            print(f"  Size: {info.size / (1024*1024):.2f} MB")
+
+        # Calculate target resolution
+        target_width, target_height = self.calculate_target_resolution(
+            info.width, info.height, max_width, max_height
+        )
+
+        # Build FFmpeg command
+        cmd = ['ffmpeg', '-i', str(input_path)]
+
+        # Video filters
+        filters = []
+        if target_width != info.width or target_height != info.height:
+            filters.append(f'scale={target_width}:{target_height}')
+
+        if filters:
+            cmd.extend(['-vf', ','.join(filters)])
+
+        # Frame rate adjustment
+        if target_fps and target_fps < info.fps:
+            cmd.extend(['-r', str(target_fps)])
+
+        # Video encoding
+        if two_pass:
+            # Two-pass encoding for better quality
+            target_bitrate = int(info.bitrate * 0.7)  # 30% reduction
+
+            # Pass 1
+            pass1_cmd = cmd + [
+                '-c:v', 'libx264',
+                '-preset', preset,
+                '-b:v', str(target_bitrate),
+                '-pass', '1',
+                '-an',
+                '-f', 'null',
+                '/dev/null' if sys.platform != 'win32' else 'NUL'
+            ]
+
+            if self.verbose or self.dry_run:
+                print(f"Pass 1: {' '.join(pass1_cmd)}")
+
+            if not self.dry_run:
+                try:
+                    subprocess.run(pass1_cmd, check=True, capture_output=not self.verbose)
+                except subprocess.CalledProcessError as e:
+                    print(f"Error in pass 1: {e}", file=sys.stderr)
+                    return False
+
+            # Pass 2
+            cmd.extend([
+                '-c:v', 'libx264',
+                '-preset', preset,
+                '-b:v', str(target_bitrate),
+                '-pass', '2'
+            ])
+        else:
+            # Single-pass CRF encoding
+            cmd.extend([
+                '-c:v', 'libx264',
+                '-preset', preset,
+                '-crf', str(crf)
+            ])
+
+        # Audio encoding
+        cmd.extend([
+            '-c:a', 'aac',
+            '-b:a', audio_bitrate
+        ])
+
+        # Output
+        cmd.extend(['-movflags', '+faststart', '-y', str(output_path)])
+
+        if self.verbose or self.dry_run:
+            print(f"Command: {' '.join(cmd)}")
+
+        if self.dry_run:
+            return True
+
+        # Execute
+        try:
+            subprocess.run(cmd, check=True, capture_output=not self.verbose)
+
+            # Get output info
+            output_info = self.get_video_info(output_path)
+            if output_info and self.verbose:
+                print(f"\nOutput video info:")
+                print(f"  Resolution: {output_info.width}x{output_info.height}")
+                print(f"  FPS: {output_info.fps:.2f}")
+                print(f"  Bitrate: {output_info.bitrate // 1000} kbps")
+                print(f"  Size: {output_info.size / (1024*1024):.2f} MB")
+                reduction = (1 - output_info.size / info.size) * 100
+                print(f"  Size reduction: {reduction:.1f}%")
+
+            return True
+
+        except subprocess.CalledProcessError as e:
+            print(f"Error optimizing video: {e}", file=sys.stderr)
+            return False
+        except Exception as e:
+            print(f"Error optimizing video: {e}", file=sys.stderr)
+            return False
+        finally:
+            # Clean up two-pass log files
+            if two_pass and not self.dry_run:
+                for log_file in Path('.').glob('ffmpeg2pass-*.log*'):
+                    log_file.unlink(missing_ok=True)
+
+    def compare_videos(self, original: Path, optimized: Path) -> None:
+        """Compare original and optimized videos."""
+        orig_info = self.get_video_info(original)
+        opt_info = self.get_video_info(optimized)
+
+        if not orig_info or not opt_info:
+            print("Error: Could not compare videos", file=sys.stderr)
+            return
+
+        print(f"\n{'Metric':<20} {'Original':<20} {'Optimized':<20} {'Change':<15}")
+        print("-" * 75)
+
+        # Resolution
+        orig_res = f"{orig_info.width}x{orig_info.height}"
+        opt_res = f"{opt_info.width}x{opt_info.height}"
+        print(f"{'Resolution':<20} {orig_res:<20} {opt_res:<20}")
+
+        # FPS
+        fps_change = opt_info.fps - orig_info.fps
+        print(f"{'FPS':<20} {orig_info.fps:<20.2f} {opt_info.fps:<20.2f} {fps_change:+.2f}")
+
+        # Bitrate
+        orig_br = f"{orig_info.bitrate // 1000} kbps"
+        opt_br = f"{opt_info.bitrate // 1000} kbps"
+        br_change = ((opt_info.bitrate / orig_info.bitrate) - 1) * 100
+        print(f"{'Bitrate':<20} {orig_br:<20} {opt_br:<20} {br_change:+.1f}%")
+
+        # Size
+        orig_size = f"{orig_info.size / (1024*1024):.2f} MB"
+        opt_size = f"{opt_info.size / (1024*1024):.2f} MB"
+        size_reduction = (1 - opt_info.size / orig_info.size) * 100
+        print(f"{'Size':<20} {orig_size:<20} {opt_size:<20} {-size_reduction:.1f}%")
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description='Video size optimization with quality/size balance.'
+    )
+    parser.add_argument(
+        'input',
+        type=Path,
+        help='Input video file'
+    )
+    parser.add_argument(
+        '-o', '--output',
+        type=Path,
+        required=True,
+        help='Output video file'
+    )
+    parser.add_argument(
+        '-w', '--max-width',
+        type=int,
+        help='Maximum width in pixels'
+    )
+    parser.add_argument(
+        '-H', '--max-height',
+        type=int,
+        help='Maximum height in pixels'
+    )
+    parser.add_argument(
+        '--fps',
+        type=float,
+        help='Target frame rate'
+    )
+    parser.add_argument(
+        '--crf',
+        type=int,
+        default=23,
+        help='CRF quality (18-28, lower=better, default: 23)'
+    )
+    parser.add_argument(
+        '--audio-bitrate',
+        default='128k',
+        help='Audio bitrate (default: 128k)'
+    )
+    parser.add_argument(
+        '--preset',
+        choices=['ultrafast', 'superfast', 'veryfast', 'faster', 'fast',
+                 'medium', 'slow', 'slower', 'veryslow'],
+        default='medium',
+        help='Encoding preset (default: medium)'
+    )
+    parser.add_argument(
+        '--two-pass',
+        action='store_true',
+        help='Use two-pass encoding (better quality)'
+    )
+    parser.add_argument(
+        '--compare',
+        action='store_true',
+        help='Compare original and optimized videos'
+    )
+    parser.add_argument(
+        '-n', '--dry-run',
+        action='store_true',
+        help='Show command without executing'
+    )
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='Verbose output'
+    )
+
+    args = parser.parse_args()
+
+    # Validate input
+    if not args.input.exists():
+        print(f"Error: Input file not found: {args.input}", file=sys.stderr)
+        sys.exit(1)
+
+    # Initialize optimizer
+    optimizer = VideoOptimizer(verbose=args.verbose, dry_run=args.dry_run)
+
+    # Check dependencies
+    if not optimizer.check_ffmpeg():
+        print("Error: FFmpeg not found", file=sys.stderr)
+        sys.exit(1)
+
+    # Optimize video
+    print(f"Optimizing {args.input.name}...")
+    success = optimizer.optimize_video(
+        args.input,
+        args.output,
+        args.max_width,
+        args.max_height,
+        args.fps,
+        args.crf,
+        args.audio_bitrate,
+        args.preset,
+        args.two_pass
+    )
+
+    if not success:
+        sys.exit(1)
+
+    # Compare if requested
+    if args.compare and not args.dry_run:
+        optimizer.compare_videos(args.input, args.output)
+
+    print(f"\nOptimized video saved to: {args.output}")
+
+
+if __name__ == '__main__':
+    main()

package/.claude/skills/mobile-development/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: mobile-development
+description: Build modern mobile applications with React Native, Flutter, Swift/SwiftUI, and Kotlin/Jetpack Compose. Covers mobile-first design principles, performance optimization (battery, memory, network), offline-first architecture, platform-specific guidelines (iOS HIG, Material Design), testing strategies, security best practices, accessibility, app store deployment, and mobile development mindset. Use when building mobile apps, implementing mobile UX patterns, optimizing for mobile constraints, or making native vs cross-platform decisions.
+license: MIT
+version: 1.0.0
+---
+
+# Mobile Development Skill
+
+Production-ready mobile development with modern frameworks, best practices, and mobile-first thinking patterns.
+
+## When to Use
+
+- Building mobile applications (iOS, Android, or cross-platform)
+- Implementing mobile-first design and UX patterns
+- Optimizing for mobile constraints (battery, memory, network, small screens)
+- Making native vs cross-platform technology decisions
+- Implementing offline-first architecture and data sync
+- Following platform-specific guidelines (iOS HIG, Material Design)
+- Optimizing mobile app performance and user experience
+- Implementing mobile security and authentication
+- Testing mobile applications (unit, integration, E2E)
+- Deploying to App Store and Google Play
+
+## Technology Selection Guide
+
+**Cross-Platform Frameworks:**
+- **React Native**: JavaScript expertise, web code sharing, mature ecosystem (121K stars, 67% familiarity)
+- **Flutter**: Performance-critical apps, complex animations, fastest-growing (170K stars, 46% adoption)
+
+**Native Development:**
+- **iOS (Swift/SwiftUI)**: Maximum iOS performance, latest features, Apple ecosystem integration
+- **Android (Kotlin/Jetpack Compose)**: Maximum Android performance, Material Design 3, platform optimization
+
+See: `references/mobile-frameworks.md` for detailed framework comparisons
+
+## Mobile Development Mindset
+
+**The 10 Commandments of Mobile Development:**
+
+1. **Performance is Foundation, Not Feature** - 70% abandon apps >3s load time
+2. **Every Kilobyte, Every Millisecond Matters** - Mobile constraints are real
+3. **Offline-First by Default** - Network is unreliable, design for it
+4. **User Context > Developer Environment** - Think real-world usage scenarios
+5. **Platform Awareness Without Platform Lock-In** - Respect platform conventions
+6. **Iterate, Don't Perfect** - Ship, measure, improve cycle is survival
+7. **Security and Accessibility by Design** - Not afterthoughts
+8. **Test on Real Devices** - Simulators lie about performance
+9. **Architecture Scales with Complexity** - Don't over-engineer simple apps
+10. **Continuous Learning is Survival** - Mobile landscape evolves rapidly
+
+See: `references/mobile-mindset.md` for thinking patterns and decision frameworks
+
+## Reference Navigation
+
+**Core Technologies:**
+- `mobile-frameworks.md` - React Native, Flutter, Swift, Kotlin, framework comparison matrices, when to use each
+- `mobile-ios.md` - Swift 6, SwiftUI, iOS architecture patterns, HIG, App Store requirements, platform capabilities
+- `mobile-android.md` - Kotlin, Jetpack Compose, Material Design 3, Play Store, Android-specific features
+
+**Best Practices & Development Mindset:**
+- `mobile-best-practices.md` - Mobile-first design, performance optimization, offline-first architecture, security, testing, accessibility, deployment, analytics
+- `mobile-debugging.md` - Debugging tools, performance profiling, crash analysis, network debugging, platform-specific debugging
+- `mobile-mindset.md` - Thinking patterns, decision frameworks, platform-specific thinking, common pitfalls, debugging strategies
+
+## Key Best Practices (2024-2025)
+
+**Performance Targets:**
+- App launch: <2 seconds (70% abandon if >3s)
+- Memory usage: <100MB for typical screens
+- Network requests: Batch and cache aggressively
+- Battery impact: Respect Doze Mode and background restrictions
+- Animation: 60 FPS (16.67ms per frame)
+
+**Architecture:**
+- MVVM for small-medium apps (clean separation, testable)
+- MVVM + Clean Architecture for large enterprise apps
+- Offline-first with hybrid sync (push + pull)
+- State management: Zustand (React Native), Riverpod 3 (Flutter), StateFlow (Android)
+
+**Security (OWASP Mobile Top 10):**
+- OAuth 2.0 + JWT + Biometrics for authentication
+- Keychain (iOS) / KeyStore (Android) for sensitive data
+- Certificate pinning for network security
+- Never hardcode credentials or API keys
+- Implement proper session management
+
+**Testing Strategy:**
+- Unit tests: 70%+ coverage for business logic
+- Integration tests: Critical user flows
+- E2E tests: Detox (React Native), Appium (cross-platform), XCUITest (iOS), Espresso (Android)
+- Real device testing mandatory before release
+
+**Deployment:**
+- Fastlane for automation across platforms
+- Staged rollouts: Internal → Closed → Open → Production
+- Mandatory: iOS 17 SDK (2024), Android 15 API 35 (Aug 2025)
+- CI/CD saves 20% development time
+
+## Quick Decision Matrix
+
+| Need | Choose |
+|------|--------|
+| JavaScript team, web code sharing | React Native |
+| Performance-critical, complex animations | Flutter |
+| Maximum iOS performance, latest features | Swift/SwiftUI native |
+| Maximum Android performance, Material 3 | Kotlin/Compose native |
+| Rapid prototyping | React Native + Expo |
+| Desktop + mobile | Flutter |
+| Enterprise with JavaScript skills | React Native |
+| Startup with limited resources | Flutter or React Native |
+| Gaming or heavy graphics | Native (Swift/Kotlin) or Unity |
+
+## Framework Quick Comparison (2024-2025)
+
+| Criterion | React Native | Flutter | Swift/SwiftUI | Kotlin/Compose |
+|-----------|--------------|---------|---------------|----------------|
+| **Stars** | 121K | 170K | N/A | N/A |
+| **Adoption** | 35% | 46% | iOS only | Android only |
+| **Performance** | 80-90% native | 85-95% native | 100% native | 100% native |
+| **Dev Speed** | Fast (hot reload) | Very fast (hot reload) | Fast (Xcode Previews) | Fast (Live Edit) |
+| **Learning Curve** | Easy (JavaScript) | Medium (Dart) | Medium (Swift) | Medium (Kotlin) |
+| **UI Paradigm** | Component-based | Widget-based | Declarative | Declarative |
+| **Community** | Huge (npm) | Growing | Apple ecosystem | Android ecosystem |
+| **Best For** | JS teams, web sharing | Performance, animations | iOS-only apps | Android-only apps |
+
+## Implementation Checklist
+
+**Project Setup:**
+- Choose framework → Initialize project → Configure dev environment → Setup version control → Configure CI/CD → Team standards
+
+**Architecture:**
+- Choose pattern (MVVM/Clean) → Setup folders → State management → Navigation → API layer → Error handling → Logging
+
+**Core Features:**
+- Authentication → Data persistence → API integration → Offline sync → Push notifications → Deep linking → Analytics
+
+**UI/UX:**
+- Design system → Platform guidelines → Accessibility → Responsive layouts → Dark mode → Localization → Animations
+
+**Performance:**
+- Image optimization → Lazy loading → Memory profiling → Network optimization → Battery testing → Launch time optimization
+
+**Quality:**
+- Unit tests (70%+) → Integration tests → E2E tests → Accessibility testing → Performance testing → Security audit
+
+**Security:**
+- Secure storage → Authentication flow → Network security → Input validation → Session management → Encryption
+
+**Deployment:**
+- App icons/splash → Screenshots → Store listings → Privacy policy → TestFlight/Internal testing → Staged rollout → Monitoring
+
+## Platform-Specific Guidelines
+
+**iOS (Human Interface Guidelines):**
+- Native navigation patterns (tab bar, navigation bar)
+- iOS design patterns (pull to refresh, swipe actions)
+- San Francisco font, iOS color system
+- Haptic feedback, 3D Touch/Haptic Touch
+- Respect safe areas and notch
+
+**Android (Material Design 3):**
+- Material navigation (bottom nav, navigation drawer)
+- Floating action buttons, material components
+- Roboto font, Material You dynamic colors
+- Touch feedback (ripple effects)
+- Respect system bars and gestures
+
+## Common Pitfalls to Avoid
+
+1. **Testing only on simulators** - Real devices show true performance
+2. **Ignoring platform conventions** - Users expect platform-specific patterns
+3. **No offline handling** - Network failures will happen
+4. **Poor memory management** - Leads to crashes and poor UX
+5. **Hardcoded credentials** - Security vulnerability
+6. **No accessibility** - Excludes 15%+ of users
+7. **Premature optimization** - Optimize based on metrics, not assumptions
+8. **Over-engineering** - Start simple, scale as needed
+9. **Skipping real device testing** - Simulators don't show battery/network issues
+10. **Not respecting battery** - Background processing must be justified
+
+## Performance Budgets
+
+**Recommended Targets:**
+- **App size**: <50MB initial download, <200MB total
+- **Launch time**: <2 seconds to interactive
+- **Screen load**: <1 second for cached data
+- **Network request**: <3 seconds for API calls
+- **Memory**: <100MB for typical screens, <200MB peak
+- **Battery**: <5% drain per hour of active use
+- **Frame rate**: 60 FPS (16.67ms per frame)
+
+## Resources
+
+**Official Documentation:**
+- React Native: https://reactnative.dev/
+- Flutter: https://flutter.dev/
+- iOS HIG: https://developer.apple.com/design/human-interface-guidelines/
+- Material Design: https://m3.material.io/
+- OWASP Mobile: https://owasp.org/www-project-mobile-top-10/
+
+**Tools & Testing:**
+- Detox E2E: https://wix.github.io/Detox/
+- Appium: https://appium.io/
+- Fastlane: https://fastlane.tools/
+- Firebase: https://firebase.google.com/
+
+**Community:**
+- React Native Directory: https://reactnative.directory/
+- Pub.dev (Flutter packages): https://pub.dev/
+- Awesome React Native: https://github.com/jondot/awesome-react-native
+- Awesome Flutter: https://github.com/Solido/awesome-flutter