Welcome to NotebookMLX! This comprehensive guide will help you get started with converting PDFs into engaging conversational podcasts using Apple's MLX framework.
- Getting Started
- Understanding the Interface
- Working with Sources
- Chat Interactions
- Studio Features
- Exporting Content
- Troubleshooting
- Tips and Best Practices
When you first open NotebookMLX, you'll see the main interface with three primary areas:
- Sources Panel (left) - Manage your PDF documents
- Chat Panel (center) - Interact with your documents
- Studio Panel (center, alternative view) - Create podcasts and mind maps
Step 1: Upload Your First Document
- Click the "Add Source" button in the Sources panel
- Select a PDF file from your computer (max 200MB)
- Wait for the document to be processed (this may take a few minutes)
- The document will appear in your Sources panel with a "Completed" status
Step 2: Start a Conversation
- Select your uploaded document by checking the box next to it
- Type a question in the chat input at the bottom
- Press Enter or click Send
- NotebookMLX will analyze your document and provide a response with citations
Step 3: Generate Your First Podcast
- Switch to the Studio panel by clicking the "Studio" tab
- Ensure your document is selected
- Choose voices for Speaker 1 and Speaker 2
- Click "Generate Podcast"
- Wait for the generation process to complete
- Listen to your generated podcast!
The application uses a tab-based interface:
- Chat Tab: Interactive Q&A with your documents
- Studio Tab: Content creation tools (podcasts, mind maps, videos)
- File Upload: Drag and drop or click to upload PDFs
- Source Selection: Check boxes to select documents for chat/generation
- Status Indicators:
- 🟡 Processing - Document is being analyzed
- 🟢 Completed - Ready for use
- 🔴 Error - Processing failed
- Search: Filter sources by filename
- Refresh: Update source status
Throughout the interface, you'll see various status indicators:
- Loading spinners: Operations in progress
- Progress bars: Show completion percentage for long tasks
- Color-coded badges: Quick status identification
- Toast notifications: Success/error messages
NotebookMLX currently supports:
- PDF documents (.pdf)
- Plain text files (.txt)
- Standard upload: Up to 200MB per file
- Large files: Automatically use chunked upload for files ≥8MB
- Total content: Up to 100,000 characters extracted per document
When you upload a document, NotebookMLX:
- Extracts text from your PDF using advanced parsing
- Chunks content into manageable sections (1000 words each)
- Cleans and preprocesses text using Qwen2.5-1.5B model
- Indexes content for fast retrieval during chat and generation
Selecting Sources:
- Check individual sources for targeted analysis
- Use "Select All" to include all completed sources
- Selected sources appear highlighted in blue
Removing Sources:
- Click the trash icon next to any source
- Confirm deletion in the popup dialog
- This permanently removes the source and its processed data
Refreshing Sources:
- Click the refresh icon to update source statuses
- Useful if processing seems stuck or to check for updates
- Select Sources: Choose one or more processed documents
- Ask Questions: Type natural language questions about your content
- Review Responses: Get detailed answers with source citations
- Follow Up: Continue the conversation with related questions
Summarization:
- "What are the main findings in this research paper?"
- "Summarize the key points of this document"
- "What are the conclusions?"
Analysis:
- "Compare the methodologies discussed"
- "What are the strengths and weaknesses mentioned?"
- "How do these results relate to previous research?"
Specific Information:
- "What does the paper say about machine learning applications?"
- "Find information about data collection methods"
- "What are the limitations mentioned?"
Creative Interpretation:
- "Explain this concept as if I'm a beginner"
- "What are the practical implications?"
- "How could this be applied in industry?"
Each response includes citations that show:
- Source Document: Which PDF the information came from
- Relevance Score: How closely the source matches your question (0-100%)
- Clickable Links: Click citations to see the source context
Clearing Chat History:
- Click the "Clear Chat" button to start fresh
- This only clears the conversation, not your sources
Exporting Conversations:
- Use the Export button to save chat history
- Available formats: PDF, HTML, Markdown, JSON
The Studio is where you create engaging content from your documents.
Basic Podcast Creation:
- Select Sources: Choose the documents you want to discuss
- Configure Speakers:
- Speaker 1: Usually the "teacher" or expert
- Speaker 2: The "curious learner" asking questions
- Choose Voices: Select from built-in or custom trained voices
- Generation Options:
- Enable "Dramatic Enhancement" for more engaging conversation
- Set target duration (optional)
- Choose conversation style
Voice Options:
-
Built-in Voices:
- Default Male/Female voices
- Multiple language options
- Ready to use immediately
-
Custom Voices:
- Train your own voices with audio samples
- Minimum 2-3 minutes of clear audio needed
- Process takes 5-15 minutes depending on quality settings
Podcast Generation Process:
- Transcript Generation (2-5 minutes): Creates conversation script
- Dramatic Enhancement (1-3 minutes): Makes dialogue more engaging
- Audio Synthesis (5-15 minutes): Converts text to speech
- Final Assembly (1-2 minutes): Combines all audio segments
Generating Mind Maps:
- Select your source documents
- Click "Generate Mind Map" in the Mind Map Studio
- Wait for processing (1-3 minutes)
- Interact with the generated visualization
Mind Map Features:
- Interactive Nodes: Click to explore topics
- Hierarchical Structure: Central topic with branching subtopics
- Source Linking: See which documents contributed to each node
- Export Options: Save as image or interactive HTML
Creating Videos from Podcasts:
- First generate a podcast (see above)
- Switch to Video Studio
- Select your completed podcast
- Choose video template:
- Simple: Static background with title
- Waveform: Animated audio visualization
- Transcript: Synchronized text display
Video Customization:
- Background colors/images
- Text overlay options
- Font and styling choices
- Transition effects
Training Custom Voices:
- Go to Voice Studio
- Click "Train New Voice"
- Upload 3-10 audio files (WAV format recommended)
- Provide voice name and description
- Choose quality setting:
- Fast: 2-5 minutes, good quality
- Balanced: 5-10 minutes, better quality
- High: 10-20 minutes, best quality
Audio Requirements for Training:
- Clear speech without background noise
- Multiple sentences/phrases
- Consistent speaking pace and tone
- Total duration: 2-10 minutes of audio
The Export Modal provides unified access to all export options:
- Click any "Export" button in the interface
- Choose your content type (Chat, Podcast, etc.)
- Select export format
- Configure options
- Download your file
PDF Export:
- Professional document format
- Includes conversation history
- Optional cover image
- Formatted for printing
HTML Export:
- Interactive web page
- Clickable citations
- Responsive design
- Easy sharing
Markdown Export:
- Plain text format
- Great for documentation
- Version control friendly
- Cross-platform compatible
JSON Export:
- Raw data format
- For developers/integration
- Includes all metadata
- Programmatic access
ZIP Package:
- Complete podcast bundle
- Audio files (WAV format)
- Transcript with timestamps
- Metadata and configuration
- Cover image (if available)
Segments JSON:
- Developer-friendly format
- Per-segment timing data
- Speaker assignments
- Audio file references
Audio Download:
- Direct MP3/WAV download
- Combined final audio
- Ready for distribution
Customization:
- Include/exclude timestamps
- Show/hide citations
- Custom filenames
- Cover image upload
Batch Operations:
- Export multiple chats at once
- Bulk podcast downloads
- Archive entire sessions
PDF Processing Fails:
- Ensure PDF is not password-protected
- Check file size (max 200MB)
- Try with a different PDF to isolate the issue
- Verify PDF contains extractable text (not just images)
Chat Responses Are Poor:
- Make sure sources are selected (blue highlighting)
- Use more specific questions
- Try rephrasing your question
- Ensure document processing completed successfully
Podcast Generation Stuck:
- Check system resources (CPU/memory usage)
- Verify selected sources are valid
- Try with fewer or smaller documents
- Restart the application if needed
Audio Quality Issues:
- Use higher quality voice settings
- Ensure good source audio for custom voices
- Check system audio settings
- Try different voice combinations
Upload Failures:
- Check internet connection
- Verify file isn't corrupted
- Try uploading a smaller file first
- Clear browser cache if using web version
For Better Performance:
- Close other resource-intensive applications
- Use shorter documents when possible
- Generate podcasts during off-peak hours
- Keep system updated
Managing System Resources:
- Monitor CPU and memory usage
- Allow adequate time for processing
- Use quality settings appropriate for your hardware
- Consider upgrading hardware for heavy usage
"ML Service Unavailable":
- MLX models are not loaded
- Check system compatibility
- Restart the application
- Verify installation
"Source Not Found":
- Source may have been deleted
- Refresh sources panel
- Re-upload if necessary
"Generation Failed":
- Check source selection
- Verify system resources
- Try with different content
- Check error logs
Document Selection:
- Use high-quality, well-structured PDFs
- Academic papers and reports work best
- Avoid heavily formatted documents
- Ensure text is machine-readable
Question Asking:
- Be specific and clear
- Ask one concept at a time
- Use proper terminology when available
- Build on previous questions for context
Podcast Creation:
- Select complementary documents for richer discussions
- Use dramatic enhancement for more engaging content
- Experiment with different voice combinations
- Consider your target audience
Efficient Source Management:
- Organize documents by project or topic
- Use descriptive filenames
- Remove unused sources regularly
- Keep source selection relevant to current task
Chat Best Practices:
- Start with broad questions, then get specific
- Save important conversations before clearing
- Use export features to preserve insights
- Take notes on key findings
Content Creation Strategy:
- Plan your podcast structure before generation
- Test voice combinations with short content first
- Create mind maps to visualize complex topics
- Use video features to enhance podcast content
Sharing Content:
- Export chats as PDFs for formal sharing
- Use HTML exports for web publishing
- Share podcast ZIPs for complete packages
- Create video content for presentations
Team Workflows:
- Establish naming conventions for sources
- Document useful question patterns
- Share successful voice configurations
- Create templates for common use cases
Professional Voice Training:
- Record in a quiet environment
- Use consistent microphone and settings
- Include various speech patterns
- Avoid background music or effects
- Speak naturally and clearly
Voice Quality Optimization:
- Use lossless audio formats when possible
- Normalize audio levels
- Remove silence at beginning/end
- Ensure consistent speaking pace
For developers interested in integrating NotebookMLX:
- RESTful API available for all major functions
- Comprehensive API documentation in
/docs/API.md - Support for programmatic source management
- Webhook support for long-running tasks
Interface Customization:
- Theme selection (light/dark)
- Panel layout preferences
- Keyboard shortcuts
- Export defaults
Model Configuration:
- Choose different MLX models for various tasks
- Adjust generation parameters
- Configure quality vs. speed tradeoffs
- Set resource limits
Documentation:
- Complete API documentation
- Component reference guides
- Architecture overview
- Development guides
Community:
- GitHub repository for issues and feature requests
- Discussion forums for user questions
- Example projects and use cases
- Regular updates and improvements
Technical Support:
- Error reporting system
- Diagnostic tools
- Performance monitoring
- Update notifications
Remember that NotebookMLX is continuously evolving. Check for updates regularly and consult the latest documentation for new features and improvements.