DOCSEARCHbyAlgolia
Submit Docs

jPSXdec Documentation

repository·readme·Indexed 19 days ago

https://github.com/m35/jpsxdec

A cross-platform utility for converting and extracting PlayStation 1 audio, video (including STR format), and TIM images. It provides a modern alternative to legacy tools with improved color accuracy and frame rate detection, featuring a command-line interface and a graphical user interface. The documentation covers the project's layered architecture, the PlayStation 1 STR video format specification, and developer guidelines for replacing XA audio, video, and TIM images.

Tokens
7.2K
Snippets
13
Records
36
Agent score
52%

What's inside jPSXdec

  1. Overview of jPSXdec

    readme

    jPSXdec is a modern, cross-platform tool designed for PlayStation 1 audio/video conversion. It is used to convert PS1 movie files and can also extract files and TIM images.

    Key features include:

    • Higher quality output compared to legacy tools.
    • Support for a wider variety of unique movie types.
    • Correct color conversion.
    • Accurate frame rate detection.
    • Cross-platform support (Windows, Mac, Linux).
    • Command-line interface (CLI) availability.

  2. How DiscIndex and DiscIndexer work together

    readme

    The DiscIndex maintains a collection of all identified DiscItems on a disc. The indexing process works as follows:

    1. Registration: DiscIndexers are registered with a DiscIndex instance.
    2. Listening: DiscIndexers register as listeners to ISectorClaimers within a SectorClaimSystem.
    3. Building: As sectors are read, the indexers identify data, build DiscItems, and add them to the DiscIndex.

    Data Structure:

    • The index is organized both as a list and a tree.
    • Sequential Access: Items are ordered by their appearance on the disc with a unique sequential ID.
    • Hierarchical Access: Items can hold child items (e.g., ISO 9660 files might contain child items representing the files within them). Children are assigned a child index based on their order within the parent.
    • Retrieval: Items can be accessed via their unique sequential ID or by their full path in the tree.

  4. How DiscItems and DiscItemSavers work

    readme

    A DiscItem represents an interesting piece of data identified on a disc that can be extracted or replaced. To perform extraction, a DiscItem generates a DiscItemSaverBuilder.

    • DiscItemSaverBuilder: Acts as the model for extraction. It allows you to configure options for how the content should be extracted and supports command-line arguments.
    • DiscItemSaverBuilderGui: Acts as the view/controller. It is a JPanel that provides an interactive interface for the options defined in the builder.

    Every DiscItem can be serialized and de-serialized as a string, which is typically stored in an index file.

  5. Understanding frame rate detection in jPSXdec

    readme

    jPSXdec attempts to achieve precise frame rate detection by analyzing the sector-based arrangement of video frames on a disc.

    Constant Frame Rate Detection

    In sector-based videos, frames are arranged so they end at the exact moment they are needed on screen. For a constant frame rate, every frame should ideally use the same number of sectors.

    • Fastest possible rate: 150 fps (1 frame per sector).
    • Slowest possible rate: Approximately 5 fps (30 sectors per frame).
    • Common rate: 15 fps (10 sectors per frame).

    Detection must account for:

    1. Fractional sectors per frame: For frame rates like 20 fps (7.5 sectors/frame), the length of frames will alternate (e.g., [7, 8, 7, 8]).
    2. Audio (XA) sectors: XA sectors are intermingled with video frames and effectively 'steal' one sector from a frame. Detection must check if a frame ends on its expected sector or the sector immediately preceding it if that sector is an XA audio sector.
    3. NTSC timing: Some videos use NTSC-adjusted rates (approx. 29.97 fps). Due to historical PlayStation development tool implementation, these videos may exhibit erratic sector layouts after the initial NTSC adjustment point (e.g., after 1000 sectors).

  6. Compare Sector-based vs. Packet-based video types

    readme

    jPSXdec distinguishes between two primary video storage methods:

    Sector-based videos (sectorbased)

    • Mechanism: Uses the PlayStation/Green Book standard of streaming real-time sector data (typically at 150 sectors/second).
    • Structure: Frames are demuxed from sectors, and audio is contained in intermingled audio sectors (often XA audio).
    • Timing: Presentation is tied to the sector stream.

    Packet-based videos (packetbased)

    • Mechanism: Does not use real-time sector streaming. Audio and video frames are packed tightly together in packets.
    • Structure: Each packet contains a video frame, a portion of SPU ADPCM audio (mono or stereo), or metadata.
    • Timing: The game engine itself handles presentation and frame rates; there is no standard storage format, as implementations vary by game.

  7. Handling Variable Frame Rate (VFR) videos

    readme

    Some videos do not use a constant frame rate. When jPSXdec identifies a variable frame rate, it faces limitations based on the output format:

    AVI Export (Constant Frame Rate Only)

    AVI files require a constant frame rate. To save a VFR video as AVI, jPSXdec uses a 'frame duplication' hack. This involves choosing a high constant frame rate (e.g., 75 fps or 150 fps) and duplicating existing frames to simulate the timing changes of a variable frame rate.

    MKV Export (Variable Frame Rate Support)

    Unlike AVI, the MKV format natively supports variable frame rates. The project roadmap includes making .mkv the default and primary export method for videos identified as having variable frame rates to ensure 100% timing accuracy without the need for frame duplication.

  8. Note on video frame replacement

    readme

    The modules.video.replace functionality is primarily effective for sector-based videos.

    Because sector-based videos have well-defined space per frame and often include empty padding sectors, replacement frames can be swapped in easily. In contrast, packet-based videos are packed tightly, meaning replacing a frame would require unpacking the entire video, modifying the data, and repacking it with updated offsets and sizes. Consequently, replacement support for packet-based videos is limited (e.g., only supported for Crusader: No Remorse).

  9. Understand jPSXdec memory management

    readme

    jPSXdec uses a relatively simple memory model. The lifecycle of memory is tied to the disc loading state:

    • Disc Loading: The root for a disc in memory consists of ICdSectorReader and DiscIndex. Once a disc is loaded, memory is not continuously allocated or released.
    • Disc Unloading: When the CdFileSectorReader is closed and discarded, all memory associated with that disc is freed (provided no internal references are held elsewhere).
    • UI Memory: Most UI components are allocated once and persist. However, the real-time audio/video player is created and destroyed every time a view is opened.
    • Disc Item Saving: The DiscItemSaverBuilder is used to save DiscItem objects. These builders are only created when a disc item is selected in the GUI and are freed when the disc is closed.

  10. Understand the jPSXdec architecture and module stack

    readme

    The project follows a layered architecture. The stack is organized from bottom to top as follows:

    1. 3rd party libraries (Foundation)
    2. javax.annotation (Nullability annotations)
    3. util (Core utilities like IO.java, util.aviwriter, and util.player)
    4. i18n (Internationalization layer)
    5. Core Format/Driver Modules: adpcm, cdreaders, formats, iso9660, psxvideo, tim
    6. Sector Management: modules.IIdentifiedSector and modules.SectorClaimSystem
    7. Data Layers: discitems and indexing
    8. Media Modules: modules.audio, modules.video, and modules.player
    9. Other Modules
    10. Entry Points: gui (Graphical User Interface) and cmdline (Command Line Interface)
    11. jpsxdec.Main (Application Root)

  11. How the Sector Claim System works

    readme

    The modules.SectorClaimSystem is used to identify multiple types of data on a disc simultaneously while avoiding false positives.

    Core Concepts

    • Claimers (ISectorClaimer): Each claimer is registered with a SectorClaimSystem. The system passes each CD sector to each claimer sequentially. Once a claimer identifies and 'claims' a sector, subsequent claimers in the chain cannot claim it.
    • Contextual Identification: Some claimers require 'lookahead' (peeking at subsequent sectors) to confirm a match. This is implemented via a recursive process: when a claimer requests a peek, the request travels back up through all other claimers to fetch the sector.
    • Listeners: Once a sector is identified, it is sent to registered listeners. These listeners process the data and forward it to further consumers (e.g., writing to a file or updating the GUI).

  12. Replace XA audio, video, and TIM images

    readme
    For developers and modders, jPSXdec provides the ability to replace existing XA audio, video, and TIM images within PlayStation 1 files. This process requires programming skills. For detailed instructions on how to perform replacements, refer to the project's manual.