Logo

User Guide

  • User Guide
    • Getting Started
      • What is zmNinjaNg?
      • Requirements
        • ZoneMinder Server
        • Client
      • Quick Start
      • Navigation and sidebar
      • Supported Features
      • What’s Different from zmNinja?
    • Installation
      • Pre-built Binaries
        • Android
        • Windows
        • macOS
        • Linux
        • iOS
      • Web Deployment
        • Build from Source
        • Example: nginx
      • Build from Source (Desktop)
      • Updating
        • Binaries
        • Web Deployment
    • Profiles
      • Adding a Profile
      • QR Code Import
      • Switching Profiles
      • Editing a Profile
      • Deleting a Profile
      • Security
      • Troubleshooting
    • Dashboard
      • Widgets
      • Customizing the Layout
      • Mobile Layout
      • Refreshing Data
    • Monitors
      • Monitor Cards
      • Filtering Monitors
      • Monitor Detail
        • Live View
        • PTZ Controls
        • Recent Events
        • Monitor Info
      • Monitor Status Indicators
      • Refresh Rate
    • Montage
      • Toolbar
      • Edit Mode
      • Fullscreen Mode
      • Pinch to Zoom
      • Streaming
      • Performance
      • Screen Size Warning
    • Events
      • Event List
      • Filtering Events
      • Event Playback
        • Video Player
        • Event Info
        • Navigation
      • Event Montage
      • Downloads
    • Timeline & Heatmap
      • Timeline
      • Filtering
      • Heatmap
      • Live Mode
      • Refresh
    • Settings
      • Appearance
        • Thumbnail display
        • TV mode
        • Hover preview
      • Hidden Monitors
      • Bandwidth Settings
      • Live Streaming
        • Streaming Protocols
        • Streaming Mode
        • Per-Monitor Streaming Override
      • Playback
      • Notification Settings
      • Advanced
        • Kiosk PIN
      • Multi-Server
    • Server
      • Version information
      • Load average
      • Disk usage
      • Status
      • Servers / Details
      • Storage areas
      • ZoneMinder control
      • Multi-server clusters
    • Notifications
      • Notification Modes
        • Event Server (ES) Mode
        • Direct Mode
      • Push Notifications (Mobile)
        • Requirements
        • Setup
        • Per-Monitor Configuration
        • Direct Mode Options
      • Notification History
      • Troubleshooting
    • Logs
      • Where the file lives
      • Buttons on the Logs page
      • Format and retention
      • Filtering and log levels
      • Live console output
      • Sharing logs for support
    • Kiosk Mode
      • Activating Kiosk Mode
        • First Use, PIN Setup
        • What Happens When Locked
      • Unlocking
        • Rate Limiting
        • Keyboard Input
      • Managing Your PIN
      • Platform Support
    • FAQ
      • General
        • What ZoneMinder version do I need?
        • Does zmNinjaNg work with self-signed certificates?
        • Linux desktop: login works but live streams and images stay black
        • Is zmNinjaNg free?
        • How is it free if you are charging for it in the playstore/appstore?
        • How is zmNinjaNg different from zmNinja?
      • Connection Issues
        • “Connection failed” when adding a profile
        • The app connects but shows no monitors
        • Cameras show but snapshots don’t load
      • Notifications
        • Why don’t push notifications work?
        • Can I get notifications on desktop?
      • Performance
        • The app is slow on my phone
        • Montage view is laggy with many cameras
      • Building
        • Can I build for iOS without a Mac?
        • Do I need an Apple Developer account?
        • The pre-built Linux binary doesn’t work
      • Debugging the Desktop App
        • How do I open the developer console on the desktop app?
      • Data & Privacy
        • Does zmNinjaNg send data to third parties?
        • Where are my credentials stored?

Developer Guide

  • Developer Guide
    • Introduction to zmNinjaNg Development
      • What is zmNinjaNg?
      • Who This Guide Is For
      • Code Examples
      • Getting Help
    • React Fundamentals
      • The mental shift
      • JSX
      • Components
      • Props: data flowing in
      • State: data the component owns
        • State updates are batched
      • Render: what triggers it
        • Each render is a snapshot
      • Hooks
      • useEffect: doing things after render
      • useRef: a value that survives renders without triggering one
      • useMemo and useCallback: stable references
      • Object identity: the bug that hides everywhere
      • React.memo: skipping unnecessary renders
      • Putting it together
      • Where to go next
    • State Management with Zustand
      • Why Global State
      • What Zustand Gives You
      • Creating a Store
        • The set Function
      • Reading State in Components
        • Selectors
        • Computed Selectors
        • useShallow: Stable Array/Object Selections
      • Actions
      • Persistence
        • Hydration
      • Calling Stores Outside React
      • Reference Equality and Infinite Loops
      • Stores in zmNinjaNg
        • Kiosk Store (stores/kioskStore.ts)
        • Background Tasks Store (stores/backgroundTasks.ts)
        • Event Favorites Store (stores/eventFavorites.ts)
      • Store Pattern
      • Testing Stores
      • Common Patterns
        • Derived state in a selector
        • Cross-store sequence
        • Conditional update
    • Pages and Views
      • Routing
        • Programmatic Navigation
      • Page Structure
      • Dashboard
        • DashboardLayout: ResizeObserver + Zustand
      • Montage
        • 12-Column Internal Grid
        • Saved Layouts
        • Layout Migration
        • Aspect-Ratio Height
        • Toolbar Toggle
        • ResizeObserver + Zustand: Same Trap
      • Monitors
      • MonitorDetail
      • Events
      • ProfileForm
      • Secondary Views
        • Logs (src/pages/Logs.tsx)
        • Notifications
        • Server (src/pages/Server.tsx)
        • Timeline (src/pages/Timeline.tsx)
      • Common Page Patterns
        • Profile requirement
        • React Query for data
        • Loading / error states
        • Navigation
    • Project Architecture
      • Directory Structure
        • Key Directories Explained
      • Component Structure
      • Monitor Components
        • MonitorCard
        • MontageMonitor
        • GridLayoutControls
        • Montage Hooks
        • PTZControls
      • Dashboard Components
        • DashboardWidget
        • Widget Types
      • Event Components
        • EventCard
        • EventThumbnailHoverPreview
        • HoverPreview (primitive)
        • MonitorHoverPreview
        • EventHeatmap
        • TagChip
      • Video Playback
        • LiveMonitorPlayer
        • Mp4EventPlayer
        • ZmsEventPlayer
        • Player Selection in EventDetail
      • Filter Components
        • GroupFilterSelect
      • QR Scanner
        • QRScanner
      • Common Components
        • RefreshButton
        • PageContainer
      • UI Components
        • SecureImage
        • PipContext
        • PasswordInput
        • CollapsibleCard
        • NotificationBadge
      • Settings Components
        • HiddenMonitorsSection
      • Kiosk Mode
        • KioskOverlay
        • PinPad
        • Kiosk Hooks
      • Component Composition
      • Testing Data Attributes
      • Key Patterns
        • 1. Memo for List Items
        • 2. Custom Hooks for Complex Logic
        • 3. Refs for DOM Access
        • 4. Stop Propagation for Nested Interactions
      • Component Communication
        • Props Down
        • Events Up
        • Global State via Zustand
      • Platform Integrations (src/services/)
        • Storage Service (lib/secureStorage.ts)
        • Connection Settings
        • Feature Deep Dive: Notifications
    • Testing Strategy
      • Cross-Platform Architecture
        • TestActions Abstraction
      • Unit Tests
        • Technology Stack
        • File Organization
        • Running Unit Tests
        • Writing Unit Tests
        • Unit Testing Rules
      • E2E Tests
        • Technology Stack
        • File Organization
        • Platform Tags
        • Writing Gherkin Feature Files
        • Step Definitions
      • Running Tests
        • Quick Reference
        • Running Device Tests Step by Step
        • Device Screenshot Capture
      • Device Setup
        • One-Time Machine Setup
        • Platform Config
        • Server Credentials
      • Visual Regression
        • Threshold
        • Generating Baselines
        • Reviewing Failures
      • Testing Workflow
        • Test-Driven Development (TDD)
        • Pre-Commit Checklist
      • Debugging Tests
        • Unit Test Debugging
        • E2E Test Debugging
        • Test Coverage
      • Troubleshooting
        • WebView context not found
        • Appium can’t find device
        • Port already in use
        • Emulator won’t boot
        • iOS build fails
    • API and Data Fetching
      • ZoneMinder API
        • Endpoint Reference
        • Authentication
        • Connection Keys (connkey)
        • Streaming Mechanics
        • Per-platform transport
        • Key Settings
        • Query Client Setup
        • Basic Queries
        • Dependent Queries
        • Polling / Auto-Refetch
        • Timers and Polling
        • Mutations
        • Infinite Queries (Pagination)
      • HTTP Client Architecture
        • Overview
        • Unified HTTP Client (src/lib/http.ts)
        • Request/Response Correlation
        • Platform-Specific Implementations
        • Proxy Support (Development)
        • Response Types
        • Error Handling
        • API Functions
      • Server API (api/server.ts)
      • Monitor API Updates (api/monitors.ts)
      • Event API Updates (api/events.ts)
      • Monitor Exclusion
      • Monitor Groups API
      • Event Tags API
      • Adjacent Event Navigation
      • Notifications API
      • Event Poller Service
      • WebSocket Notification Service
      • End-to-end Flow: Viewing Monitors
      • Error Handling
        • API Errors
        • React Query Error Handling
      • ZoneMinder Streaming Protocol
        • Stream Lifecycle
        • Never Render Without a Valid ConnKey
        • Stream Modes
        • ZMS Commands
    • Common Pitfalls
      • React Pitfalls
        • 1. Using Non-Primitive Dependencies in useCallback
        • 2. Forgetting to Cleanup useEffect
        • 3. Rendering Streams Before Connection Key is Valid (Zombie Streams)
        • 4. Mutating State Directly
        • 5. Missing Keys in Lists
        • 6. Conditional Hooks
      • Zustand Pitfalls
        • 7. Using Store Values as Dependencies
        • 8. Forgetting to Initialize Store State
      • React Query Pitfalls
        • 9. Missing enabled Flag
        • 10. Not Invalidating Queries After Mutations
        • 11. Incorrect Query Keys
      • Testing Pitfalls
        • 12. Hardcoded Values in E2E Tests
        • 13. Not Mocking Dependencies in Unit Tests
        • 14. Forgetting to Add data-testid
      • Performance Pitfalls
        • 15. Not Memoizing Expensive Calculations
        • 16. Not Memoizing Components in Lists
        • 17. Creating New Object References in Component Body
        • 18. Store-to-Component Sync Circular Dependencies
      • Internationalization Pitfalls
        • 19. Hardcoded User-Facing Text
        • 20. Forgetting to Update All Language Files
      • Cross-Platform Pitfalls
        • 21. Invisible Overlays Blocking Touch Events on iOS
      • Platform-Specific Pitfalls
        • 24. ZMS Streaming URLs Hang Forever When Downloading Snapshots
      • Security Pitfalls
        • 22. Storing Sensitive Data Unencrypted
        • 23. Logging Sensitive Data
      • Checklist: Pre-Code Review
    • Contributing to zmNinjaNg
      • Before You Start
      • Development Workflow
        • 1. Pick or Create an Issue
        • 2. Create a Branch
        • 3. Write Code
        • 4. Run Tests
        • 5. Commit Changes
        • 6. Push and Create Pull Request
        • 7. Code Review
        • 8. Merge
      • Code Review Guidelines
        • Functional Requirements
        • Code Quality
        • Testing
        • Guidelines Compliance
        • Performance
        • Security
      • Common Contribution Scenarios
        • Adding a New Feature
        • Fixing a Bug
        • Updating Documentation
      • Style Guide
        • TypeScript
        • React Components
        • Naming Conventions
      • Mobile Development
        • Prerequisites
        • Running on Device/Emulator
        • Workflow
      • Getting Help
      • License
      • Recognition
    • Key Libraries
      • UI and Visualization
        • react-grid-layout
        • video.js
        • lucide-react
        • @radix-ui/*
      • Data and Logic
        • date-fns & date-fns-tz
        • react-hook-form & zod
        • @tanstack/react-query
      • Mobile and Platform
        • @capacitor/*
      • Internationalization
        • i18next & react-i18next
      • Constants Organization
        • zm-constants.ts
        • zmninja-ng-constants.ts
    • Application Lifecycle
      • 1. The Entry Point (index.html → main.tsx)
      • 2. Bootstrapping Phase (App.tsx)
        • Data Hydration
        • Profile Bootstrap
        • Bootstrap Server Map
        • Bootstrap Cancellation
        • Initialization Complete
      • 3. The Authentication Flow
        • A. Token Exchange
        • B. The “Refresh Loop”
      • 4. The “Main Loop” (Runtime)
      • 5. Mobile Lifecycle (Capacitor)
        • Backgrounding
        • Resuming
      • 6. Navigation Lifecycle
    • Shared Services and Reusable Components
      • Shared Services (lib/)
        • Logger (lib/logger.ts)
        • HTTP Client (lib/http.ts)
        • SSL Trust (lib/ssl-trust.ts)
        • Discovery (lib/discovery.ts)
        • Download Utilities (lib/download.ts)
        • Proxy URL Utilities (lib/proxy-utils.ts)
        • Server Resolver (lib/server-resolver.ts)
        • URL Builder (lib/url-builder.ts)
        • Event Icons (lib/event-icons.ts)
        • Time Utilities (lib/time.ts)
        • Crypto Utilities (lib/crypto.ts)
        • Secure Storage (lib/secureStorage.ts)
        • Platform Detection (lib/platform.ts)
        • App Version (lib/version.ts)
        • Safe-Area Bootstrap (lib/safe-area-bootstrap.ts)
        • API Validator (lib/api-validator.ts)
        • Grid Utils (lib/grid-utils.ts)
        • Bandwidth Settings (lib/zmninja-ng-constants.ts)
        • Monitor Rotation (lib/monitor-rotation.ts)
        • Event Utilities (lib/event-utils.ts)
        • Monitor Filters (lib/filters.ts)
        • Profile Settings Accessor (lib/profile-settings.ts)
        • Group-Keyed Montage Settings (stores/settings.ts)
        • Stream Lifecycle (hooks/useStreamLifecycle.ts)
      • Reusable UI Components
        • Button (ui/button.tsx)
        • Card (ui/card.tsx)
        • Dialog (ui/dialog.tsx)
        • Popover (ui/popover.tsx)
        • SecureImage (ui/secure-image.tsx)
        • EventThumbnail (events/EventThumbnail.tsx)
        • VideoPlayer (ui/video-player.tsx)
        • PasswordInput (ui/password-input.tsx)
        • EmptyState (ui/empty-state.tsx)
        • PullToRefresh (ui/pull-to-refresh-indicator.tsx)
        • QuickDateRangeButtons (ui/quick-date-range-buttons.tsx)
        • Select (ui/select.tsx)
        • Switch (ui/switch.tsx)
        • Badge (ui/badge.tsx)
        • Progress (ui/progress.tsx)
      • Shared Hooks (hooks/)
        • useEventFilters (hooks/useEventFilters.ts)
        • Event Notes Display
        • Sidebar Navigation Reorder
      • Reusable Domain Components
        • MonitorFilterPopover (filters/MonitorFilterPopover.tsx)
        • EventsFilterPopover (events/EventsFilterPopover.tsx)
        • BackgroundTaskDrawer (BackgroundTaskDrawer.tsx)
      • Usage Matrix
      • Adding New Shared Services
        • 1. Choose the Right Location
        • 2. Document Usage
        • 3. Follow Patterns
        • 4. Test
        • Navigation Service (lib/navigation.ts)
        • Notification Services (services/)
        • Kiosk PIN Utility (lib/kioskPin.ts)
        • log-file (lib/log-file/)
      • Token freshness gate
    • External Network Endpoints
      • Endpoints
      • Notes
    • Go2RTC WebRTC Streaming Integration
      • Overview
      • Architecture
        • Component Hierarchy
        • Key Files
      • Stream Selection Logic
        • Decision Tree
        • Settings
      • Fallback Ladder
        • How Fallback Works
      • Implementation Details
        • VideoRTC Library (Vendored)
        • URL Building
        • Discovery
      • StreamChannel
      • Fallback Chain
      • Controls
      • Type Definitions
        • Monitor Fields
        • Profile Fields
      • Testing Strategy
        • Unit Tests
        • E2E Tests
        • Manual Testing Checklist
      • Edge Cases Handled
        • 1. Go2RTC Unavailable
        • 2. Monitor Not Configured for Go2RTC
        • 3. WebRTC Connection Failure
        • 4. Missing RTSPStreamName
        • 5. Null Profile
        • 6. Missing Video Ref
        • 7. WebSocket Signaling Failure
        • 8. Network Interruption
      • Troubleshooting
        • Issue: VideoPlayer shows “Connection failed”
        • Issue: WebRTC connects but no video
        • Issue: Fallback to MJPEG always happens
        • Issue: Snapshot download produces black image
        • Issue: Picture-in-Picture not working
      • Performance Considerations
        • WebRTC Benefits
        • Potential Issues
        • Optimization Tips
      • Configuration Examples
        • ZoneMinder Monitor Configuration
        • Go2RTC Configuration
        • zmNinjaNg Profile Settings
      • Security Considerations
        • Authentication
        • CORS
        • HTTPS
      • References
      • Future Enhancements
        • Potential Improvements
        • Not Planned
    • Quick Reference
      • State Types
      • File Organization
      • Development Quick Start

Building

  • Building for Mobile & Desktop
    • Prerequisites
    • Web Build
    • Desktop Build (Electron)
      • macOS Code Signing: Avoiding Keychain Prompts
    • Mobile Builds
      • Android Build Guide
        • Prerequisites
        • Environment Setup
        • Project Setup
        • Push Notifications Setup
        • Building and Running
        • Troubleshooting
        • Next Steps
      • iOS Build Guide
        • Prerequisites
        • Environment Setup
        • Project Setup
        • Push Notifications Setup
        • Building and Running
        • Troubleshooting
        • Testing on Physical Devices
        • Next Steps
    • Versioning
    • Automated Releases

Related Projects

  • zmesNg
  • pyzmNg
zmNinjaNg
  • Search

© Copyright 2025-2026, pliablepixels.

Built with Sphinx using a theme provided by Read the Docs.