Metadata-Version: 2.4
Name: fmstream
Version: 1.0.1
Summary: A Python library for scraping FM radio station data from fmstream.org
Home-page: https://github.com/fmstream-py/fmstream
Author: HaoWasabi
Author-email: truonggiahao24@example.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: beautifulsoup4>=4.9.0
Requires-Dist: fastapi>=0.68.0
Requires-Dist: pydantic>=1.8.0
Requires-Dist: uvicorn>=0.15.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Provides-Extra: api
Requires-Dist: fastapi>=0.68.0; extra == "api"
Requires-Dist: pydantic>=1.8.0; extra == "api"
Requires-Dist: uvicorn>=0.15.0; extra == "api"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# FMStream Library

A Python library for scraping FM radio station data from fmstream.org with REST API support.

## Features

- Extract FM radio station information (title, location, frequency, etc.)
- Parse audio stream URLs from JavaScript data
- Intelligent matching of stations with their corresponding streams
- Clean, structured data models using dataclasses
- Type hints for better code documentation
- FastAPI REST API with filtering and search capabilities
- Compatible with fmstream.org API parameters

## Installation

```bash
pip install fmstream
```

For API server support:
```bash
pip install fmstream[api]
```

## Quick Start

### Python Library Usage

```python
from fmstream import FMStreamScraper

# Scrape radio station data from a fmstream.org URL
url = "https://fmstream.org/index.php?s=vietnam"
scraper = FMStreamScraper()
stations = scraper.scrape_stations(url)

# Access station information
for station in stations:
    print(f"Station: {station.title}")
    print(f"Location: {station.location}")
    print(f"Frequency: {station.frequency}")
    print(f"Streams: {len(station.streams)}")
    
    # Access audio streams
    for stream in station.streams:
        print(f"  - {stream.title}: {stream.url}")
```

### REST API Usage

Start the API server:

```python
import uvicorn
from fmstream import fastapi_app

uvicorn.run(fastapi_app, host="0.0.0.0", port=8000)
```

Or use the example script:

```bash
python examples/api_server.py
```

Access the API:

```bash
# Get all stations
curl "http://localhost:8000/fmstream-api"

# Search for stations
curl "http://localhost:8000/fmstream-api?s=vietnam"

# Get featured stations
curl "http://localhost:8000/fmstream-api?c=FT"

# Filter by genre/style
curl "http://localhost:8000/fmstream-api?style=pop"
```

API Documentation: http://localhost:8000/docs

### API Parameters

- `c`: Country code (ITU), "FT" for featured, "RD" for random
- `hq`: High quality audio (0/1)
- `l`: Language (ISO code)
- `n`: Offset (skip n entries)
- `o`: Order/filter (top, big, med, sma, or letter)
- `s`: Search string
- `style`: Station style/genre

## API Reference

### FMStreamScraper

Main scraper class with methods:

- `scrape_stations(url)` - Complete scraping process
- `extract_station_info(url)` - Extract station metadata only
- `extract_audio_streams(url)` - Extract stream data only
- `match_station_to_group(title, groups)` - Match station to stream group

### Data Models

- `RadioStation` - Complete radio station with metadata and streams
- `AudioStream` - Individual audio stream with title and URL
- `StreamGroup` - Group of related audio streams


## Legal & Data Source Notice

- This library uses data scraped from [fmstream.org](https://fmstream.org/).
- **For non-commercial use only.** No ads, no fees, no user tracking.
- Do **not** store or aggregate stream URLs or metadata in your own database.
- You must clearly credit fmstream.org as the data source and provide a visible link in your application.
- You are solely responsible for any legal issues arising from use of this data.
- See [fmstream.org API Terms](https://fmstream.org/api.htm) for full conditions.

## Requirements

- Python 3.7+
- requests
- beautifulsoup4
- fastapi (for API server)
- pydantic (for API server)
- uvicorn (for API server)

## License

[MIT License][def]


[def]: LICENSE
