|
| 1 | +# Tatakai webOS TV App |
| 2 | + |
| 3 | +A production-ready Netflix-style anime streaming application designed for LG webOS smart TVs, built with Next.js, React, and optimized for remote control navigation. |
| 4 | + |
| 5 | +## Features |
| 6 | + |
| 7 | +- **TV-Optimized Interface**: Designed specifically for 10-foot viewing experience with large, readable typography |
| 8 | +- **Remote Control Navigation**: Full support for LG TV remote control with arrow keys, OK, Back, and colored buttons |
| 9 | +- **Netflix-Style Layout**: Hero section with auto-rotating spotlight and horizontal content rows |
| 10 | +- **Spatial Navigation**: Advanced focus management for seamless DPAD navigation |
| 11 | +- **Anime Streaming**: Integration with HiAnime API for thousands of anime titles |
| 12 | +- **Design System**: Based on design tokens from `1design.json` for consistent theming |
| 13 | +- **Performance Optimized**: Built for TV hardware limitations with efficient rendering |
| 14 | + |
| 15 | +## Tech Stack |
| 16 | + |
| 17 | +- **Framework**: Next.js 15 (App Router) with static export for webOS |
| 18 | +- **UI**: Tailwind CSS with custom TV-optimized utilities |
| 19 | +- **State Management**: TanStack Query for server state, Zustand for client state |
| 20 | +- **Motion**: Framer Motion for smooth animations |
| 21 | +- **Icons**: Lucide React |
| 22 | +- **Platform**: LG webOS TV integration with native APIs |
| 23 | + |
| 24 | +## Project Structure |
| 25 | + |
| 26 | +``` |
| 27 | +tatakai-webos-tv/ |
| 28 | +├── app/ # Next.js App Router pages |
| 29 | +│ ├── layout.tsx # Root layout with providers |
| 30 | +│ ├── page.tsx # Home page with hero and rows |
| 31 | +│ ├── providers.tsx # React Query and Focus providers |
| 32 | +│ └── globals.css # Global styles and TV utilities |
| 33 | +├── components/ # React components |
| 34 | +│ ├── layout/ # Header and navigation |
| 35 | +│ ├── hero/ # Hero/billboard section |
| 36 | +│ ├── rows/ # Content carousels |
| 37 | +│ ├── cards/ # Anime cards |
| 38 | +│ ├── player/ # Video player (planned) |
| 39 | +│ └── dialogs/ # Modals and overlays (planned) |
| 40 | +├── lib/ # Utilities and integrations |
| 41 | +│ ├── api-client.ts # HiAnime API client |
| 42 | +│ ├── focus-management.tsx # TV focus and key handling |
| 43 | +│ ├── webos-integration.ts # LG webOS platform APIs |
| 44 | +│ └── design-tokens.ts # Design system integration |
| 45 | +├── scripts/ # Build and packaging scripts |
| 46 | +│ └── package-webos.js # WebOS packaging utility |
| 47 | +├── appinfo.json # WebOS app manifest |
| 48 | +├── next.config.js # Next.js configuration for TV |
| 49 | +└── tailwind.config.js # TV-optimized Tailwind theme |
| 50 | +``` |
| 51 | + |
| 52 | +## Quick Start |
| 53 | + |
| 54 | +### 1. Clone and Setup |
| 55 | +```bash |
| 56 | +cd tatakai-webos-tv |
| 57 | +npm install |
| 58 | +cp .env.example .env.local |
| 59 | +``` |
| 60 | + |
| 61 | +### 2. Development |
| 62 | +```bash |
| 63 | +npm run dev |
| 64 | +# Open http://localhost:3000 |
| 65 | +# Test with keyboard navigation (arrows + enter) |
| 66 | +``` |
| 67 | + |
| 68 | +### 3. Production Build |
| 69 | +```bash |
| 70 | +npm run build |
| 71 | +npm run start |
| 72 | +``` |
| 73 | + |
| 74 | +### 4. Deploy to webOS TV |
| 75 | +```bash |
| 76 | +# Build and package |
| 77 | +npm run build |
| 78 | +npm run webos:package |
| 79 | + |
| 80 | +# Install webOS CLI (one-time) |
| 81 | +npm install -g @webosose/ares-cli |
| 82 | + |
| 83 | +# Deploy to TV |
| 84 | +ares-package webos-package/ |
| 85 | +ares-install com.tatakai.webostv_1.0.0_all.ipk -d [YOUR_TV] |
| 86 | +ares-launch com.tatakai.webostv -d [YOUR_TV] |
| 87 | +``` |
| 88 | + |
| 89 | +## Building for webOS TV |
| 90 | + |
| 91 | +### 1. Build the App |
| 92 | + |
| 93 | +```bash |
| 94 | +npm run build |
| 95 | +``` |
| 96 | + |
| 97 | +This creates an optimized static export in the `dist/` directory. |
| 98 | + |
| 99 | +### 2. Package for webOS |
| 100 | + |
| 101 | +```bash |
| 102 | +npm run webos:package |
| 103 | +``` |
| 104 | + |
| 105 | +This creates a webOS-ready package in the `webos-package/` directory. |
| 106 | + |
| 107 | +### 3. Deploy to TV |
| 108 | + |
| 109 | +#### Install webOS CLI (one-time setup): |
| 110 | +```bash |
| 111 | +npm install -g @webosose/ares-cli |
| 112 | +``` |
| 113 | + |
| 114 | +#### Connect to your TV: |
| 115 | +```bash |
| 116 | +ares-setup-device |
| 117 | +# Follow prompts to add your TV |
| 118 | +``` |
| 119 | + |
| 120 | +#### Install and launch: |
| 121 | +```bash |
| 122 | +# Package the app |
| 123 | +ares-package webos-package/ |
| 124 | + |
| 125 | +# Install on TV |
| 126 | +ares-install com.tatakai.webostv_1.0.0_all.ipk -d [DEVICE_NAME] |
| 127 | + |
| 128 | +# Launch the app |
| 129 | +ares-launch com.tatakai.webostv -d [DEVICE_NAME] |
| 130 | +``` |
| 131 | + |
| 132 | +## API Integration |
| 133 | + |
| 134 | +The app integrates with the HiAnime API for anime content: |
| 135 | + |
| 136 | +- **Base URL**: `https://aniwatch-api-taupe-eight.vercel.app` |
| 137 | +- **Endpoints**: Home page, search, anime details, episodes, streaming data |
| 138 | +- **Features**: Trending, popular, latest episodes, genres, top 10 lists |
| 139 | + |
| 140 | +See `lib/api-client.ts` for full API documentation. |
| 141 | + |
| 142 | +## Remote Control Mapping |
| 143 | + |
| 144 | +### Navigation Keys: |
| 145 | +- **Arrow Keys**: Move focus between elements |
| 146 | +- **OK/Enter**: Select focused element |
| 147 | +- **Back**: Go back or close modals |
| 148 | +- **Home**: Return to home screen |
| 149 | + |
| 150 | +### Color Keys (Shortcuts): |
| 151 | +- **Red Button**: Search |
| 152 | +- **Green Button**: Profile/Account |
| 153 | +- **Yellow Button**: Settings |
| 154 | +- **Blue Button**: Help |
| 155 | + |
| 156 | +### Media Keys: |
| 157 | +- **Play/Pause**: Toggle playback |
| 158 | +- **Rewind/Fast Forward**: Seek video |
| 159 | +- **Stop**: Stop playback |
| 160 | + |
| 161 | +## Design System |
| 162 | + |
| 163 | +The app uses design tokens from `1design.json`: |
| 164 | + |
| 165 | +- **Colors**: Dark theme with purple accent (#8A2BE2) |
| 166 | +- **Typography**: TV-optimized font sizes (18px-48px) |
| 167 | +- **Spacing**: Consistent spacing scale (4px-96px) |
| 168 | +- **Focus**: High-contrast focus rings for accessibility |
| 169 | +- **Motion**: Smooth animations optimized for TV hardware |
| 170 | + |
| 171 | +## Performance Considerations |
| 172 | + |
| 173 | +- **TV-Safe Areas**: 5% horizontal, 3% vertical padding |
| 174 | +- **Large Touch Targets**: Minimum 48px for remote accuracy |
| 175 | +- **Smooth Scrolling**: Hardware-accelerated transforms |
| 176 | +- **Memory Management**: Efficient DOM rendering and cleanup |
| 177 | +- **Network Handling**: Retry logic and offline graceful degradation |
| 178 | + |
| 179 | +## Browser Compatibility |
| 180 | + |
| 181 | +- **Primary**: webOS TV browser (Chromium-based) |
| 182 | +- **Development**: Modern browsers (Chrome, Firefox, Safari, Edge) |
| 183 | +- **Fallbacks**: Progressive enhancement for older TV browsers |
| 184 | + |
| 185 | +## Contributing |
| 186 | + |
| 187 | +1. Fork the repository |
| 188 | +2. Create a feature branch (`git checkout -b feature/amazing-feature`) |
| 189 | +3. Test on TV resolution (1920x1080) |
| 190 | +4. Ensure keyboard-only navigation works |
| 191 | +5. Commit changes (`git commit -m 'Add amazing feature'`) |
| 192 | +6. Push to branch (`git push origin feature/amazing-feature`) |
| 193 | +7. Open a Pull Request |
| 194 | + |
| 195 | +## License |
| 196 | + |
| 197 | +This project is licensed under the MIT License - see the LICENSE file for details. |
| 198 | + |
| 199 | +## Support |
| 200 | + |
| 201 | +For issues and questions: |
| 202 | +- Check the browser console for errors |
| 203 | +- Test network connectivity to API endpoints |
| 204 | +- Verify webOS TV compatibility |
| 205 | +- Review focus management and key handling |
0 commit comments